doc/release-process.md

   1 Release Process
   2 ====================
   3 Meta: There should always be a single release engineer to disambiguate responsibility.
   4
   5 If this is a hotfix release, please see `./hotfix-process.md` before proceeding.
   6
   7 ## Pre-release
   8
   9 ### Github Milestone
  10
  11 Ensure all goals for the github milestone are met. If not, remove tickets
  12 or PRs with a comment as to why it is not included. (Running out of time
  13 is a common reason.)
  14
  15 ### Pre-release checklist:
  16
  17 Check that dependencies are properly hosted by looking at the `check-depends` builder:
  18
  19   https://ci.z.cash/#/builders/1
  20
  21 Check that there are no surprising performance regressions:
  22
  23   https://speed.z.cash
  24
  25 Ensure that new performance metrics appear on that site.
  26
  27 Update `src/chainparams.cpp` nMinimumChainWork with information from the getblockchaininfo rpc.
  28
  29 ### Protocol Safety Checks:
  30
  31 If this release changes the behavior of the protocol or fixes a serious
  32 bug, verify that a pre-release PR merge updated `PROTOCOL_VERSION` in
  33 `version.h` correctly.
  34
  35 If this release breaks backwards compatibility or needs to prevent
  36 interaction with software forked projects, change the network magic
  37 numbers. Set the four `pchMessageStart` in `CTestNetParams` in
  38 `chainparams.cpp` to random values.
  39
  40 Both of these should be done in standard PRs ahead of the release
  41 process. If these were not anticipated correctly, this could block the
  42 release, so if you suspect this is necessary, double check with the
  43 whole engineering team.
  44
  45 ## Release dependencies
  46
  47 The release script has the following dependencies:
  48
  49 - `help2man`
  50 - `debchange` (part of the devscripts Debian package)
  51
  52 You can optionally install the `progressbar2` Python module with pip to have a
  53 progress bar displayed during the build process.
  54
  55 ## Release process
  56
  57 In the commands below, <RELEASE> and <RELEASE_PREV> are prefixed with a v, ie.
  58 v1.0.9 (not 1.0.9).
  59
  60 ### Create the release branch
  61
  62 Run the release script, which will verify you are on the latest clean
  63 checkout of master, create a branch, then commit standard automated
  64 changes to that branch locally:
  65
  66     $ ./zcutil/make-release.py <RELEASE> <RELEASE_PREV> <RELEASE_FROM> <APPROX_RELEASE_HEIGHT>
  67
  68 Examples:
  69
  70     $ ./zcutil/make-release.py v1.0.9 v1.0.8-1 v1.0.8-1 120000
  71     $ ./zcutil/make-release.py v1.0.13 v1.0.13-rc1 v1.0.12 222900
  72
  73 ### Create, Review, and Merge the release branch pull request
  74
  75 Review the automated changes in git:
  76
  77     $ git log master..HEAD
  78
  79 Push the resulting branch to github:
  80
  81     $ git push '[email protected]:$YOUR_GITHUB_NAME/zcash' $(git rev-parse --abbrev-ref HEAD)
  82
  83 Then create the PR on github. Complete the standard review process,
  84 then merge, then wait for CI to complete.
  85
  86 ## Make tag for the newly merged result
  87
  88 Checkout master and pull the latest version to ensure master is up to date with the release PR which was merged in before.
  89
  90     $ git checkout master
  91     $ git pull --ff-only
  92
  93 Check the last commit on the local and remote versions of master to make sure they are the same:
  94
  95     $ git log -1
  96
  97 The output should include something like, which is created by Homu:
  98
  99     Auto merge of #4242 - nathan-at-least:release-v1.0.9, r=nathan-at-least
 100
 101 Then create the git tag. The `-s` means the release tag will be
 102 signed. **CAUTION:** Remember the `v` at the beginning here:
 103
 104     $ git tag -s v1.0.9
 105     $ git push origin v1.0.9
 106
 107 ## Make and deploy deterministic builds
 108
 109 - Run the [Gitian deterministic build environment](https://github.com/zcash/zcash-gitian)
 110 - Compare the uploaded [build manifests on gitian.sigs](https://github.com/zcash/gitian.sigs)
 111 - If all is well, the DevOps engineer will build the Debian packages and update the
 112   [apt.z.cash package repository](https://apt.z.cash).
 113
 114 ## Add release notes to GitHub
 115
 116 - Go to the [GitHub tags page](https://github.com/zcash/zcash/tags).
 117 - Click "Add release notes" beside the tag for this release.
 118 - Copy the release blog post into the release description, and edit to suit
 119   publication on GitHub. See previous release notes for examples.
 120 - Click "Publish release" if publishing the release blog post now, or
 121   "Save draft" to store the notes internally (and then return later to publish
 122   once the blog post is up).
 123
 124 Note that some GitHub releases are marked as "Verified", and others as
 125 "Unverified". This is related to the GPG signature on the release tag - in
 126 particular, GitHub needs the corresponding public key to be uploaded to a
 127 corresponding GitHub account. If this release is marked as "Unverified", click
 128 the marking to see what GitHub wants to be done.
 129
 130 ## Post Release Task List
 131
 132 ### Deploy testnet
 133
 134 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:
 135
 136 * builds Zcash based on the specified branch
 137 * deploys it as a public service (e.g. betatestnet.z.cash, mainnet.z.cash)
 138 * 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
 139 * possible manual steps: blowing away the `testnet3` dir, deleting old parameters, restarting DNS seeder
 140
 141 Then, verify that nodes can connect to the testnet server, and update the guide on the wiki to ensure the correct hostname is listed in the recommended zcash.conf.
 142
 143 ### Update the 1.0 User Guide
 144
 145 This also means updating [the translations](https://github.com/zcash/zcash-docs).
 146 Coordinate with the translation team for now. Suggestions for improving this
 147 part of the process should be added to #2596.
 148
 149 ### Publish the release announcement (blog, github, zcash-dev, slack)
 150
 151 ## Celebrate