zcash/doc/release-process.md

272 lines
11 KiB
Markdown

Release Process
====================
Meta: There should always be a single release engineer to disambiguate responsibility.
If this is a hotfix release, please see the [Hotfix Release
Process](https://github.com/zcash/zcash/blob/master/doc/hotfix-process.md) documentation
before proceeding.
## Pre-release
### Github Milestone
Ensure all goals for the github milestone are met. If not, remove tickets
or PRs with a comment as to why it is not included. (Running out of time
is a common reason.)
### Pre-release checklist:
Check that dependencies are properly hosted.
Check that there are no surprising performance regressions.
Update `src/chainparams.cpp` nMinimumChainWork with information from the getblockchaininfo rpc.
Check that dependencies are up-to-date or have been postponed. If necessary,
install `cargo-upgrades` and `cargo-audit`:
```
cargo install cargo-upgrades cargo-audit
```
Then run each of the following:
```
$ ./qa/zcash/updatecheck.py
$ cargo upgrades
$ cargo audit
```
You can optionally create a file `~/.local/share/zcash/updatecheck/token` (or
`$XDG_DATA_HOME/zcash/updatecheck/token` if the `XDG_DATA_HOME` environment
variable is set) to avoid running into GitHub rate limiting. Create an
unprivileged personal access token on GitHub and copy the value into the file.
If there are updates that have not been postponed, review their changelogs
for urgent security fixes, and if there aren't any, postpone the update by
adding a line to `qa/zcash/postponed-updates.txt`.
### Protocol Safety Checks:
If this release changes the behavior of the protocol or fixes a serious
bug, verify that a pre-release PR merge updated `PROTOCOL_VERSION` in
`version.h` correctly.
If this release breaks backwards compatibility or needs to prevent
interaction with software forked projects, change the network magic
numbers. Set the four `pchMessageStart` in `CTestNetParams` in
`chainparams.cpp` to random values.
Both of these should be done in standard PRs ahead of the release
process. If these were not anticipated correctly, this could block the
release, so if you suspect this is necessary, double check with the
whole engineering team.
## Release dependencies
The release script has the following dependencies:
- `help2man`
- `debchange` (part of the devscripts Debian package)
- the python modules `progressbar2` (optional - displays a progress bar),
`requests` and `xdg`
## Versioning
Zcash version identifiers have the format `vX.Y.Z` with the following conventions:
* Increments to the `X` component (the "major version") correspond to network
upgrades. A network upgrade occurs only when there is a change to the
consensus rules.
* Increments to the `Y` component (the "minor version") correspond to regular
Zcash releases. These occur approximately every 6 weeks and may include breaking
changes to public APIs.
* Increments to the `Z` component occur only in the case of hotfix releases.
## Release candidate & release process
Identify the commit from which the release stabilization branch will be made.
Release stabilization branches are used so that development can proceed
unblocked on the `master` branch during the release candidate testing and
bug-fixing process. By convention, release stabilization branches are named
`version-X.Y.0` where `X` and `Y` are the major and minor versions for the
release.
In the commands below, <RELEASE> and <RELEASE_PREV> must identify `git` tags
prefixed with the character `v`, i.e. `v1.0.9` (not `1.0.9`). <COMMIT_ID> is a
`git` hash identifying the commit on which a release stabilization or release
branch will be based. It is recommended to use the entire hash value to
identify the commit, although a prefix of at least 10 characters is also
permitted.
### Create the release stabilization branch
Having identified the commit from which the release will be made, the release
manager constructs the release stabilization branch as follows:
$ git checkout -b version-X.Y.0 <COMMIT_ID>
$ git push 'git@github.com:zcash/zcash' $(git rev-parse --abbrev-ref HEAD)
### Review & update the release notes
Now is the time to make sure that all of the changes since the previous release
are property represented in `doc/release-notes.md`. Determine the tag that will
be used for the `RELEASE_FROM` value by manually searching for the tag for the
latest full release in the list obtained by running
$ git tag -l --sort=-taggerdate
and then finding the most recent non-release-candidate version. If you have a
git remote for the upstream `bitcoin-core` repository, be aware that Bitcoin
tags will also appear in this list. Then, skim the full diff since the last
release and make certain that all user-visible changes are properly documented
in `doc/release-notes.md`.
$ git diff <RELEASE_FROM>..HEAD
If you make any changes to the release notes, add commits to do so as
necessary, but do NOT push these commits to the `version-X.Y.Z` branch on the
upstream repository; they will be included in the release branch that will be
created in the next step.
### Create the release branch
Run the release script to create the release branch. This will create a branch
based upon the specified commit ID, then commit standard automated changes to
that branch locally:
$ ./zcutil/make-release.py <COMMIT_ID> <RELEASE> <RELEASE_PREV> <RELEASE_FROM> <APPROX_RELEASE_HEIGHT>
Examples:
$ ./zcutil/make-release.py 600c4acee1 v1.1.0-rc1 v1.0.0 v1.0.0 280300
$ ./zcutil/make-release.py b89b48cda1 v1.1.0 v1.1.0-rc1 v1.0.0 300600
Ordinarily, we choose a release height that is a couple hundred blocks in
the future in order to give time for CI to run.
If it is necessary that the version you are building reach its end-of-service
halt in less time than the ordinary 16 weeks, it may be necessary to modify
the value of the `RELEASE_TO_DEPRECATION_WEEKS` constant in `deprecation.h`
prior to running `make-release.py`.
### Create, Review, and Merge the release branch pull request
Review the automated changes in git:
$ git log version-X.Y.0..HEAD
Push the resulting branch to github:
$ git push 'git@github.com:$YOUR_GITHUB_NAME/zcash' $(git rev-parse --abbrev-ref HEAD)
Then create the PR on github targeting the `version-X.Y.0` branch. Complete the
standard review process and wait for CI to complete.
## Make a tag for the tip of the release branch
NOTE: This has changed from the previously recommended process. The tag should
be created at the tip of the automatically-generated release branch created by
the release script; this ensures that any changes made to the release
stabilization branch since the initiation of the release process are not
accidentally tagged as being part of the release as a consequence of having
been included in a merge commit.
Check the last commit on the local and remote versions of the release branch to
make sure they are the same:
$ git log -1
If you haven't previously done so, set the gpg key id you intend to use for
signing:
git config --global user.signingkey <keyid>
Then create the git tag. The `-s` means the release tag will be signed. Enter
"Release <version>." and save when prompted for a commit message. **CAUTION:**
Remember the `v` at the beginning here:
$ git tag -s vX.Y.Z[-rcN]
For release tags (not release candidates) copy the "Notable Changes" section of
the release notes into the tag body when creating the tag. This makes it easy
for command-line `git` users to review the changes in a release without having
to check out the tag.
$ git push origin vX.Y.Z[-rcN]
## Merge the release branch to the release stabilization branch
Once CI has completed and the release branch has sufficient approving reviews,
merge the release branch back to the release stabilization branch. Testing
proceeds as normal. Any changes that need to be made during the release
candidate period are made by submitting PRs targeting the release stabilization
branch.
Subsequent release candidates, and the creation of the final release, follow
the same process as for release candidates, omitting the `-rcN` suffix for the
final release.
## Make and deploy deterministic builds
- Run the [Gitian deterministic build environment](https://github.com/zcash/zcash-gitian)
- Compare the uploaded [build manifests on gitian.sigs](https://github.com/zcash/gitian.sigs)
- If all is well, the DevOps engineer will build the Debian packages and update the
[apt.z.cash package repository](https://apt.z.cash).
## Add release notes to GitHub
The following part of the release process applies only to final releases, not
release candidates.
- Go to the [GitHub tags page](https://github.com/zcash/zcash/tags).
- Click "Add release notes" beside the tag for this release.
- Copy the "Notable Changes" section of the release notes into the release
description, and edit to suit publication on GitHub. See previous release
notes for examples.
- Click "Publish release" if publishing the release blog post now, or
"Save draft" to store the notes internally (and then return later to publish
once the blog post is up).
Note that some GitHub releases are marked as "Verified", and others as
"Unverified". This is related to the GPG signature on the release tag - in
particular, GitHub needs the corresponding public key to be uploaded to a
corresponding GitHub account. If this release is marked as "Unverified", click
the marking to see what GitHub wants to be done.
## Post Release Task List
### Merge the release stabilization branch
Once the final release branch has merged to the release stabilization branch, a
new PR should be opened for merging the release stabilization branch into
master. This may require fixing merge conflicts (e.g. changing the version
number in the release stabilization branch to match master, if master is
ahead). Such conflicts **MUST** be addressed with additional commits to the
release stabilization branch; specifically, the branch **MUST NOT** be rebased
on master.
Once any conflicts have been resolved, the release stabilization branch should
be merged back to the `master` branch, and then deleted.
### Deploy testnet
Notify the Zcash DevOps engineer/sysadmin that the release has been tagged. They update
some variables in the company's automation code and then run an Ansible playbook, which:
* builds Zcash based on the specified branch
* deploys it as a public service (e.g. testnet.z.cash, mainnet.z.cash)
* often the same server can be re-used, and the role idempotently handles upgrades, but if
not then they also need to update DNS records
* possible manual steps: blowing away the `testnet3` dir, deleting old parameters,
restarting DNS seeder.
Verify that nodes can connect to the mainnet and testnet servers.
Update the [Zcashd Full Node and CLI](https://zcash.readthedocs.io/en/latest/rtd_pages/zcashd.html)
documentation on ReadTheDocs to give the new version number.
### Publish the release announcement (blog, github, zcash-dev, slack)
## Celebrate