Commit 5f41bc2f authored by Lars Wirzenius's avatar Lars Wirzenius
Browse files

docs: update release process: more explicit

Also, split off steps that can be scripted later.

Sponsored-by: author
parent a54a051c
Pipeline #344714615 passed with stage
in 10 minutes and 1 second
---
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.
4. Run `cargo publish` in any crates that have changed since the
previous release.
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.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment