Releasing Neptune Core

This section describes the steps to publish a new version of Neptune Core, and to release & distribute its binary artifacts.

Pre-requisites

The following tools are used to ensure a high quality release.

Use the following commands to install the needed tools. If you decide against using cargo binstall, it's generally possible to just cargo install instead. Some tools might require cargo install --locked.

cargo install cargo-binstall
cargo binstall cargo-semver-checks
cargo binstall git-cliff
cargo binstall cargo-release
cargo binstall cargo-dist

Release Process Checklist

Not every step of the release process is (or should be) fully automated. An example of a semi-automated step is changelog generation. Tools like git cliff help, but a manual edit is necessary to reduce noise and achieve the polish appreciated by readers of the changelog. An example of a fully automated step is assembly and distribution of binaries by dist.

Set Working Directory to Workspace Root

Unless indicated otherwise, the current working directory is assumed to be the workspace root.

cd /path/to/neptune-core

Check Distribution Workflow Files

Run dist init to generate the latest GitHub workflow files that will take care of binary distribution. The interface allows to add or remove target platforms as well as installers. Feel free to change those settings, but be aware that not all installers are equally well supported; you might want to inform yourself before changing anything.

Usually, the generated GitHub workflow files are identical to the existing ones. In this case, move on to the next step. If the workflow files have changed, commit them. An appropriate commit message could be: ci: Update release workflow files

Bump Version

Bump the version in Cargo.toml as appropriate.

Confirm Version Bump as Semantic

ℹ️ Because binaries cannot be used as a dependency, this step is only relevant if Neptune Core has library targets.

Make sure that the version bump conforms to semantic versioning.

cargo semver-checks

Generate Changelog Addition

Summarize the changes introduced since the last version. Consistent use of Conventional Commits and git cliff get you started:

git cliff v0.0.1..HEAD -t vX.Y.Z > /tmp/change_diff.md
#         ~~~~~~~          ~~~~~~
#            |             the to-be-released version
#            |
#         at least 2 versions back for the GitHub “compare” link to work

If new commit types were introduced since the last release, git cliff will not know about them. You can recognize the commit types unknown to git cliff by the missing associated emoji in the corresponding headline in the generated changelog addition. Add the new commit types to cliff.toml and rerun the above command.

Polish the Changelog Addition

Make the changelog addition (/tmp/change_diff.md) concise. This is a manual step.

Feel free to delete entries generously. For example, a branch that builds up to a certain feature might have a series of commits that are relevant for development and review. Users of Neptune Core probably only care about the feature itself; they should not be bombarded with minute details of its development process. Should they be interested in more details, the changelog will have a link to the commit that introduced the feature. From there, they can start their own journey of discovery.

If you find an entry in the changelog addition confusing or irrelevant, then with high probability, so will users of Neptune Core; delete the changelog entry, or investigate its meaning and rewrite it.

Focus only on the new version, even though the changelog addition contains sections for older versions. The changelogs for those older versions are already in the CHANGELOG.md, and should probably not be touched.

Amend CHANGELOG.md

Copy the now-polished changelog addition from /tmp/change_diff.md into CHANGELOG.md.

Commit

Add and commit the changed files.

git add Cargo.toml
git add CHANGELOG.md
git commit -m "chore: Release vX.Y.Z"
#                              ~~~~~
#                              the new version

Ensure that Tests Pass

Make sure all tests pass, preferably by waiting for GitHub's CI to finish. Alternatively, run them locally:

cargo test --all-targets

Publish to crates.io

The tool cargo-release helps to publish multiple, possibly inter-depending crates with a single command.

ℹ️ If the workspace has only one member, cargo publish (instead of cargo release) works fine. With cargo publish, you will need to create git tags manually.

cargo release --execute --no-push
#             ~~~~~~~~~ ~~~~~~~~~
#                 |     gives you time to review the created git tag(s)
#                 |
#             omit this to get a dry run

Get Green Light from Continuous Integration

Create a new git branch with the release commit and push it to GitHub. Open a pull request from that branch. Wait for continuous integration to do its job.

Once CI gives the green light, fast-forward the master branch to the tip of the feature branch and push it.

Push Tag to GitHub

In a previous step, cargo-release automatically created one or multiple git tags. Edit them until you are happy, then push the tag(s) to GitHub.

cargo release --execute push

Set Branch release

By convention, branch release should always point to the latest stable commit compatible with the latest release.

git checkout release
git reset --hard master
git push --force-with-lease

Check Release Artifacts & Page

Pushing the git tag(s) triggers CI once more. After CI has done its job, check the release page to see if everything looks okay.

🎉 Congrats on the new release!