# Release process for Subplot

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 (from leaf to binary):

- `subplot`
- `subplotlib-derive`
- `subplotlib`
- `subplot-bin`

To find all crates, run the following at the root of the source tree:

~~~sh
git ls-files | grep Cargo.toml | grep -v examples
~~~

Before starting the release process proper, follow the steps in the tutorial
on the website (<https://subplot.tech/tutorial/) and make sure all steps work,
and the process still makes sense. If not, start a side quest to get things
fixed or the tutorial updated.

Run these at the root of the source tree, and either fix anything
that's found, or at least report it on the issue tracker:

1. `cargo audit`
2. `cargo deny --workspace check`

Do these for each crate, with leaf crates in the dependency tree
first:

1. Check that the dependency versions on any other Subplot crates are
   correct.
2. Run `cargo update` and `cargo outdated` for the crate, and make any
   needed updates.
3. 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.
4. 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.
   You may wish to use `cargo semver-checks -p PACKAGE` to check if it
   recommends a stronger version update than you had already chosen.
5. Run `cargo publish --dry-run --allow-dirty` and fix any problems.

For the top crate `subplot` additionally do the following:

1. Run `make` 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.
   Particularly check the [Fixed in next version][fixedstuff] issues
   against the NEWS.
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.
   Ensure the MR contains references to close all of the
   [Fixed in next version][fixedstuff] issues so that all the issue
   authors get notified of the release.

[fixedstuff]: https://gitlab.com/subplot/subplot/-/issues?label_name[]=fixed-in-next-version

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 to build and public a Debian package on `apt.liw.fi`.
6. Announce our jubilation to the world via blog posts and other
   suitable channels.
   - fediverse, with #subplot hashtag
   - Subplot website blog
   - personal blogs
