Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

release: update release guide #167

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

release: update release guide #167

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
110 changes: 46 additions & 64 deletions docs/release-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,71 +1,8 @@
# Release process

This project uses [cargo-release][cargo-release] in order to prepare new releases, to tag and sign relevant git commit and to publish the resulting artifacts to [crates.io][crates-io].

This project uses [cargo-release][cargo-release] in order to prepare new releases, tag and sign the relevant git commit, and publish the resulting artifacts to [crates.io][crates-io].
The release process follows the usual PR-and-review flow, allowing an external reviewer to have a final check before publishing.

This document gives an high-level overview as well as a step-by-step guide on how to perform a release.
lucab marked this conversation as resolved.
Show resolved Hide resolved

## Overview

Most of the process is automated with the help of cargo-release and its metadata entries in Cargo manifest.
This helper is in charge of bumping the `version` field in the manifest in a dedicated commit, attaching the correspoding signed tag to it, and then producing another commit to prepare the project for the next development cycle.

The two resulting commits can be then submitted in a dedicated PR and reviewed.
Once merged, the last steps of the process consist in pushing the git tag and publishing the crate.

## Steps

If this is the first time, make sure all the requirements from the section below are met.

This guide assumes that you have push access to the upstream repository of the project.
Since this is required to push the new tag we have decided to also place the PR branch on the upstream repository.

These steps show how to release version `x.y.z` on the `upstream` remote (this can be checked via `git remote -av`).

For each release to be published, proceed as follows:

#### 1. Make sure the project is clean and prepare the environment

* `cargo test`
* `cargo clean`
* `git clean -fd`
* `export RELEASE_VER=x.y.z`
* `export UPSTREAM_REMOTE=upstream`

#### 2. Create release commits on a dedicated branch and tag it

* `git checkout -b release-${RELEASE_VER}`
* This will create the tag after asking for version confirmation:

`cargo release`

#### 3. Open a PR for this release

* `git push ${UPSTREAM_REMOTE} release-${RELEASE_VER}`
* Open a web browser and create a Pull Request for the branch above
* Make sure the resulting PR contains exactly two commits

#### 4. Get the PR reviewed, approved and merged

#### 5. Publish the artifacts (tag and crate)

* `git push ${UPSTREAM_REMOTE} ${RELEASE_VER}`
* Make sure the upstream tag matches the local tag:

`git fetch --tags --verbose ${UPSTREAM_REMOTE} 2>&1 | grep ${RELEASE_VER}`
* `git checkout ${RELEASE_VER}`
* Make sure the tag is what you intend to release; if so this will show an empty output:

`git diff release-${RELEASE_VER}~1 ${RELEASE_VER}`
* `cargo publish`

#### 6. Clean up the environment

* `unset RELEASE_VER`
* `unset UPSTREAM_REMOTE`
* `cargo clean`

## Requirements

This guide requires:
Expand All @@ -75,6 +12,51 @@ This guide requires:
* GPG setup and personal key for signing
* `cargo` (suggested: latest stable toolchain from [rustup][rustup])
* `cargo-release` (suggested: `cargo install -f cargo-release`)
* A verified account on crates.io
* Write access to this GitHub project

## Release checklist

These steps show how to release version `x.y.z` on the `origin` remote (this can be determined via `git remote -av`).
Push access to the upstream repository is required in order to publish the new tag and the PR branch.

1. make sure the project is clean and prepare the environment:
- [ ] `cargo test`
- [ ] `cargo clean`
- [ ] `git clean -fd`
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm uncertain whether to leave the -d parameter to remove untracked files in here or not. At least we should add a warning about it.

- [ ] `RELEASE_VER=x.y.z`
- [ ] `UPSTREAM_REMOTE=origin`

:warning:: `UPSTREAM_REMOTE` should reference the locally configured remote that points to the upstream git repository.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
:warning:: `UPSTREAM_REMOTE` should reference the locally configured remote that points to the upstream git repository.
:warning: `UPSTREAM_REMOTE` should reference the locally configured remote that points to the upstream git repository.


2. create release commits on a dedicated branch and tag it:
- [ ] `git checkout -b release-${RELEASE_VER}`
- [ ] `cargo release` (and confirm the version when prompted)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For a minor release I had to run cargo release -- minor, as the RELEASE_VER environment variable is not considered by cargo release. Should we add a note on this or do we trust this to be intuitive enough?


3. open a PR for this release:
- [ ] `git push ${UPSTREAM_REMOTE} release-${RELEASE_VER}`
- [ ] open a web browser and create a PR for the branch above
- [ ] make sure the resulting PR contains exactly two commits
- [ ] in the PR body, write a short changelog with relevant changes since last release

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change

4. [ ] get the PR reviewed, approved and merged

5. publish the artifacts (tag and crate):
- [ ] `git checkout v${RELEASE_VER}`
- [ ] verify that `grep "^version = \"${RELEASE_VER}\"$" Cargo.toml` produces output
- [ ] `git push ${UPSTREAM_REMOTE} v${RELEASE_VER}`
- [ ] `cargo publish`

6. publish the release:
- [ ] open a web browser and create a GitHub Release for the tag above
- [ ] write a short changelog (i.e. re-use the PR content) and publish the release

7. clean up the environment:
- [ ] `cargo clean`
- [ ] `git checkout master`
- [ ] `git pull ${UPSTREAM_REMOTE} master`
- [ ] `git push ${UPSTREAM_REMOTE} :release-${RELEASE_VER}`
- [ ] `git branch -d release-${RELEASE_VER}`

[cargo-release]: https://github.com/sunng87/cargo-release
[rustup]: https://rustup.rs/
Expand Down