The path to 0.5

[tjkirch]

Since we have a few breaking changes lined up for 0.5, I thought it'd be good to have an issue to track them and be confident they're all lined up together. (While another minor version wouldn't be the end of the world, avoiding churn is nice.)

We can also track the relevant doc updates, and authors can suggest wording for their changes.

Tasks related to breaking changes since 0.4.x:

• Add error checks for attribute misuse and duplication - Improve errors for misused attributes #109
• source(from) implies source(true) - Make source(from) imply source(true) #129
• Replace backtrace(delegate) with backtrace on a source field - Replace backtrace(delegate) with backtrace on a source field #141
• Error when source/backtrace(false) given on wrong field - Should error when source/backtrace(false) given on wrong field #140
• Update snafu::guide::upgrading for above
• Update CHANGELOG.md for above
• shepmaster release process: version bumps, pushes, etc.

[tjkirch]

@shepmaster, please feel free to edit the issue or my comments here as you like - in case I misrepresented or forgot anything, if you want to add other requirements, or just to close the issue if it's not helpful! A GitHub Milestone could also provide similar tracking, using separate issues for the bullets; I could help with that, too, if you prefer it. I'm just hoping I can help, I don't want to change your process.

I plan to suggest changelog/upgrading wording for my changes in comments here or perhaps as a PR.

[tjkirch]

Suggestion for snafu::guide::upgrading: https://gist.github.com/tjkirch/bb9bf6b950b2466d16b1a71b0f52862d

I can put this and other suggestions in a PR if/when desired.

[tjkirch]

Suggestion for CHANGELOG.md for 0.5.0:

## [0.5.0] - UNRELEASED

### Changed
- Made `source(from)` imply `source`; you can remove `source` if you
  had both.

### Fixed
- Add compiler errors for attribute misuse and duplication.
- Fix parsing of multiple attributes inside `#[snafu(...)]`.

### Removed
- Replaced `backtrace(delegate)` with `backtrace` on source fields.

[shepmaster]

Suggestion for CHANGELOG.md

I'd keep the focus of the changelog on end-user-facing aspects. The contributor's guide and compatibility-tests are for developers of SNAFU, so I'd leave them out.

Roughly, I try to tag the issues / PRs with the maintenance tag to help sort those out. Too bad there's no GitHub UI for git log LAST_VERSION.. that shows those tags...

[shepmaster]

A GitHub Milestone could also provide similar tracking, using separate issues for the bullets; I could help with that, too, if you prefer it. I'm just hoping I can help, I don't want to change your process.

I don't have much of a process, so no worries there! I don't have an opinion between a milestone or a tracking issue, TBH; whichever works.

[tjkirch]

I'd keep the focus of the changelog on end-user-facing aspects. The contributor's guide and compatibility-tests are for developers of SNAFU, so I'd leave them out.

Removed.

[CryZe]

@tjkirch The no_std PR is a breaking change due to adding a new std feature for all those using default-features = false, so ideally it would be part of 0.5 as well. The PR is done from my side too.

[tjkirch]

@CryZe Cool! Batching breaking changes makes sense if they're ready. I'm going to let @shepmaster edit the list above, though, since I don't understand the change nearly as well (not a core user).

@shepmaster - I'm assigning this issue to you because the two currently open PRs that might block 0.5 are ready for your review, and the next task would be deciding whether to do the release. :)

[shepmaster]

I'm OK with spreading multiple breaking changes across versions, so long as we minimize the groups affected by back-to-back changes. 0.5 will have breaking changes for people using backtrace(delegate) and misusing attributes, so I'd be sad to have those people affected by a 0.6. If 0.6

If we feel that there's any reason to not merge the no_std changes, I think it's OK going to a 0.6. Likewise, it seems plausible we will upgrade to syn/quote 1.0 at some point, which will definitely be a separate release. These three groups of breaking changes are unlikely to affect the same people; most people can just bump the version number (or ideally have dependabot do it for them)

I've been lax at reviewing the no_std PR because I'm still not sure what I feel about the concept; I'll try to set some time aside this weekend to review.

[tjkirch]

@shepmaster Would you be willing to accept help on the syn/quote/proc-macro2 upgrade? Even if you decide not to bump the requirement to Rust 1.31 in #154, it could be something we keep in a branch for inspiration when the time comes, and we could include Rust 2018 commits, etc. And if you do bump the requirement, maybe it could go in the same breaking release... (I don't know what would be breaking about a syn* bump yet :))

[tjkirch]

I've got a prototype of the syn update, Rust 1.31 minimum requirement, and Rust 2018 update in commits in https://github.com/tjkirch/snafu/commits/upgrade-minimum . I didn't want to create an issue because I'm not sure how @shepmaster wants to think about that, and I'm sure some of the changes in my commits are debatable (for example removing vs. replacing the rust_1_30 feature) but I was curious and wanted to see what it would take. The syn upgrade was almost free, in terms of our code changes! If the Rust 1.31 minimum seems like an obvious decision based on #154 feedback, perhaps it could be part of 0.5.

[shepmaster]

I've been lazy over the last few weeks, so I think it makes sense to release 0.5 with what we have now, then evaluate the backtrace (#157) and no-std (#138) changes for the next breaking release. As I mentioned earlier, I don't think there's anything wrong with releasing a 0.6 and/or 0.7, even if we magically get around to it in the next week or so. I'll be on vacation next week, which historically has meant that I'm either very attached to a computer or not at all 😉

[shepmaster]

Would you be willing to accept help on the syn/quote/proc-macro2 upgrade?

Certainly! As you found out, our minimum changes to use syn/quote 1.x are really small. One thing that I'd be interested in exploring is making more use of the powers given by the new versions, maybe mostly in quote. For example all of the repetition things mentioned are issues we encountered.

I've had a mild sense that snafu-derive's lib.rs is simply too big at this point and could benefit from some reorganization. Perhaps reviewing the code during such reorganization would be a good time.

I don't know what would be breaking about a syn* bump yet

Mostly that syn 1.x doesn't support Rust 1.18 anymore, so it breaks our compatibility promises, which I feel means we do a semver-incompatible bump.

I'm not sure how @shepmaster wants to think about that

Me either! 🤣

[shepmaster]

Now that we have a baseline for using an issue, let's try a GH project for 0.6!

[shepmaster]

Posted about 0.5 to URLO