diff options
author | Daniel Silverstone <dsilvers+gitlab@digital-scurf.org> | 2021-08-01 10:36:34 +0000 |
---|---|---|
committer | Daniel Silverstone <dsilvers+gitlab@digital-scurf.org> | 2021-08-01 10:36:34 +0000 |
commit | 0d0bc0ef86964a28b66916e344ab55f704838ced (patch) | |
tree | 4fcba78b021f9a6e3005f33c89c1d5af4b6073f7 | |
parent | 31170280362e6a9827aee0090ef19b875245f0df (diff) | |
parent | 543b28baa033947f17774cd8266dd1d9798f1b7f (diff) | |
download | subplot-0d0bc0ef86964a28b66916e344ab55f704838ced.tar.gz |
Merge branch 'release-automatable' into 'main'
docs: update release process: more explicit
Closes #208
See merge request subplot/subplot!193
-rw-r--r-- | RELEASE.md | 90 |
1 files changed, 57 insertions, 33 deletions
@@ -1,42 +1,66 @@ --- title: Release process for Subplot +author: The Subplot project ... -The subplot project consists of serveral crates, any step which refers to the -`Cargo.toml` or `Cargo.lock` files should be repeated for all crates. Currently -the set of crates to consider for release is: +The Subplot project consists of several crates. They can be released +independently from each other. However, there is only one `NEWS.md` +file with release notes, and only one set of Debian packaging (only +the binaries and template resources are packaged). The crates are, +currently: - `subplotlib-derive` - `subplotlib` - `subplot` -When determining if a new version of a crate is required, use `git log` with -appropriate filters. - -Before any release of Subplot, it is appropriate to ensure that versions of -dependencies have been updated where needed. You may want to do this on a -different branch, or as part of the release branch. - -Follow these steps to make a release of Subplot - -1. Create a branch on which to do the release (e.g. call it `release`) -2. Ensure dependencies are up-to-date, for example, `cargo update` and its - associated tool `cargo outdated` will be of help. -3. Update `NEWS.md` as appropriate -4. Update the version numbers everywhere they need to be updated. Use - [semantic versioning](https://semver.org/) appropriately. You may use - the [bumper](https://bumper.liw.fi/) tool to do this. - - `NEWS.md` - - `Cargo.toml` - - `debian/changelog` -5. Ensure everything is appropriately committed with good messages. -6. Run `cargo publish --dry-run` for each crate as needed, to ensure that - we will be okay to publish the crates later. -7. Push the branch to Gitlab and create the merge request. -8. Have someone review, approve (assuming green CI), and merge the release - branch. -9. Create a signed, annotated, Git tag `vX.Y.Z` for version `X.Y.Z` of Subplot. -10. Push the tag to Gitlab and to `git.liw.fi` -11. Publish any changed crates to `crates.io` with `cargo publish` in the - relevant directories. -12. Announce our jubilation to the world. +To find all crates, run the following at the root of the source tree: + +~~~sh +git ls-files | grep Cargo.toml +~~~ + +Do these for each crate, with leaf crates in the dependency tree +first: + +1. Run `cargo update` and `cargo outdated` for the crate, and make any + needed updates. +2. Review changes in the crate (`git log -p .` in the crate's + sub-directory). Update the top level `NEWS.md` with any changes + that users of Subplot need to be aware of. +3. Update the crate's `Cargo.toml` with the appropriate version number + for the new release, if there's been any changes. If any of the + other crates depend on this crate, update their dependency + information in their `Cargo.toml` as needed. +4. Run `cargo publish --dry-run` and fix any problems. + +For the top crate `subplot` additionally do the following: + +1. Run `./check` and fix anything that needs fixing to make it finish + successfully. +2. Update `NEWS.md` with an end-user oriented summary of the changes + in all crates since the previous release, if there are any. +3. Update `debian/changelog` with a summary of any changes to the + Debian packaging. Use the `dch` command to edit the file to get the + format right: `dch -v X.Y.Z-1 "New release"` to start a new + version, `dch "foo bar"` to add a new bullet point to a version, + and `dch -r ""` to mark the version as ready for release. +4. Commit the changes in all crates and submit as a merge request via + GitLab. + +Once the above changes have been merged, make the actual release (note +that these steps are meant to be possible to automate, later on, and +require no review cycle): + +1. Pull down the above changes from GitLab. +2. Create a signed, annotated, git tag `X.Y.Z` for version `X.Y.Z` of + the Subplot project (`git tag -sam "Subplot release X.Y.Z" X.Y.Z`). + We don't tag releases of the other crates. +3. Run `git push --tags gitlab` to push the tag to Gitlab. Replace + `gitlab` with whatever name you use in git for the remote that is + gitlab.com. +4. Run `cargo publish` in any crates that have changed since the + previous release, from the leaves toward the root. +5. Ask Lars or Daniel to pull the tag from GitLab and push it to + `git.liw.fi` so that a Debian package gets built and published. +6. Announce our jubilation to the world via blog posts and other + suitable channels. |