Release.md: document preparation sections
I've split this into "what I do in the days leading up to the release" and "what I do right before the release". There's a lot more detail now, including: * up-to-date invocations for `cargo upgrade` * up-to-date changelog instructions * our current version-bumping instructions * possible side-effects from version bumps.
This commit is contained in:
Nick Mathewson
parent
451306df72
commit
d0e00e4f4e
|
|
@ -56,22 +56,129 @@ release" below.
|
|||
|
||||
## Preparing for the release
|
||||
|
||||
1. For 0.0.x, we do a toplevel changelog only.
|
||||
Note that you can do these steps _in parallel_ with "are we ready to
|
||||
release?" above.
|
||||
|
||||
I made the toplevel changelog for 0.0.1 by reading 'git shortlog
|
||||
arti-v0.0.0..' and summarizing the best stuff.
|
||||
1. Check for breaking changes to our dependencies.
|
||||
In the weeks between releases, I try to run:
|
||||
`cargo upgrade --dry-run --compatible=ignore --incompatible=allow`.
|
||||
This will tell us if any of our dependencies
|
||||
have new versions that will not upgrade automatically.
|
||||
|
||||
There is a ./maint/thanks script to generate the acknowledgments.
|
||||
2. Check for non-breaking changes to our dependencies.
|
||||
A day or two before release, I try to run:
|
||||
`cargo update`.
|
||||
This will replace each of our dependencies in Cargo.lock
|
||||
with the latest version.
|
||||
(I recommend doing this a bit before the release
|
||||
to make sure that we have time
|
||||
to deal with any surprising breakage.)
|
||||
|
||||
2. Make sure we're up-to-date. Try to run:
|
||||
* cargo update
|
||||
* cargo upgrade --dry-run --workspace --skip-compatible
|
||||
3. Write a changelog.
|
||||
|
||||
(Note that not all of the above will make changes on their own; you'll
|
||||
need to understand the output and decide what to do.)
|
||||
I start by running
|
||||
`git log --reverse arti-v${LAST_VERSION}..`,
|
||||
and writing a short summary of everything I find into
|
||||
new sections of the changelog.
|
||||
I try to copy the list of sections
|
||||
from previous changelogs, to keep them consistent.
|
||||
|
||||
3. Then make sure that CI passes. *Also ensure we've run tests for all
|
||||
possible Cargo feature combinations, as per arti#303.*
|
||||
If I have to take a break in the middle,
|
||||
or if time will pass between now and the release,
|
||||
I add a note like
|
||||
`UP TO DATE WITH 726f666c2d2d6d61646520796f75206c6f6f6b21`
|
||||
to remind me where I need to start again.
|
||||
|
||||
4. Finish the changelog.
|
||||
|
||||
When the changelog is done, pipe it into
|
||||
`maint/gen_md_links` to auto-generate markdown links
|
||||
to our gitlab repositories.
|
||||
Then, fill in the URLs for any links that the script
|
||||
couldn't find.
|
||||
|
||||
Run `maint/thanks arti-v${LAST_VERSION}`
|
||||
to generate our list of ackowledgments;
|
||||
insert this into the changelog.
|
||||
|
||||
Add an acknowledgement for the current sponsor(s).
|
||||
|
||||
4. Determine what crates have semver changes.
|
||||
|
||||
We need to sort our crates into the following tiers.
|
||||
* No changes were made.
|
||||
(No version bump needed)
|
||||
* Only non-functional changes were made.
|
||||
(Bump the version of the crate, but not the depended-on version.)
|
||||
* Functional changes were made, but no APIs were added or broken.
|
||||
(Bump patchlevel.)
|
||||
* APIs were added.
|
||||
(Bump patchlevel if major == 0; else bump minor.)
|
||||
* APIs were broken.
|
||||
(Bump minor if major == 0; else bump major.)
|
||||
|
||||
You can identify crates that have no changes (by elimination)
|
||||
with `./maint/changed_crates ${LAST_VERSION}`.
|
||||
|
||||
To see whether a crate has only non-functional changes,
|
||||
you have to use `git diff`. Sorry!
|
||||
Historically, trivial changes
|
||||
are small tweaks in the clippy lints,
|
||||
or documentation/comment improvements.
|
||||
|
||||
To determine whether any APIs were added,
|
||||
look in the semver.md files.
|
||||
(We often forget to add these;
|
||||
but fortunately,
|
||||
most of our crates currently have major version 0,
|
||||
so we don't need to distinguish "functional changes"
|
||||
from "new APIs".)
|
||||
|
||||
To determine whether any APIs were broken,
|
||||
look in the semver.md files.
|
||||
The `cargo semver-checks` tool
|
||||
can also identify some of these,
|
||||
but its false-negative rate is high.
|
||||
|
||||
You may also want to look over the crate-by-crate diffs.
|
||||
This can be quite time-consuming.
|
||||
|
||||
## Final preparation for a release.
|
||||
|
||||
Wait! Go back and make sure
|
||||
that you have done everything in the previous sections
|
||||
before you continue!
|
||||
|
||||
1. Finalize the changelog.
|
||||
|
||||
Make sure that the date is correct.
|
||||
Make sure that the acknoweldgments and links are correct,
|
||||
if they might have gotten stale.
|
||||
|
||||
2. Increase all appropriate version numbers.
|
||||
|
||||
To do this, run for each crate with functional changes:
|
||||
`cargo set-version --bump {patch|minor|major} -p ${CRATE}`.
|
||||
|
||||
For crates with non-functional changes,
|
||||
you need to edit the Cargo.toml files.
|
||||
We have [a ticket][#945] to automate this.
|
||||
|
||||
[#945]: https://gitlab.torproject.org/tpo/core/arti/-/issues/945
|
||||
|
||||
3. Check for side effects from bumping versions!
|
||||
|
||||
Is there a Cargo.lock change you forgot to commit?
|
||||
If so, commit it.
|
||||
|
||||
Does a previously unchanged crate
|
||||
depend on a crate that got a version bump?
|
||||
Now _that_ crate counts as changed,
|
||||
and needs a version bump of its own.
|
||||
|
||||
4. Then make sure that CI passes, again.
|
||||
|
||||
## The actual release itself.
|
||||
|
||||
## Actually releasing
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue