doc/release-process.md

   1 Release Process
   2 ====================
   3 Meta: There should always be a single release engineer to disambiguate responsibility.
   4
   5 ## Pre-release
   6
   7 Check all of the following:
   8
   9 - All dependencies have been updated as appropriate:
  10   - BDB
  11   - Boost
  12   - ccache
  13   - libgmp
  14   - libsnark (upstream of our fork)
  15   - libsodium
  16   - miniupnpc
  17   - OpenSSL
  18
  19 ## A. Define the release version as:
  20
  21     $ ZCASH_RELEASE=MAJOR.MINOR.REVISION(-BUILD_STRING)
  22
  23 Example:
  24
  25     $ ZCASH_RELEASE=1.0.0-beta2
  26
  27 Also, the following commands use the `ZCASH_RELEASE_PREV` bash variable for the
  28 previous release:
  29
  30     $ ZCASH_RELEASE_PREV=1.0.0-beta1
  31
  32 ## B. Create a new release branch / github PR
  33 ### B1. Update (commit) version in sources
  34
  35     README.md
  36     src/clientversion.h
  37     configure.ac
  38     contrib/gitian-descriptors/gitian-linux.yml
  39
  40 In `configure.ac` and `clientversion.h`:
  41
  42 - Increment `CLIENT_VERSION_BUILD` according to the following schema:
  43
  44   - 0-24: `1.0.0-beta1`-`1.0.0-beta25`
  45   - 25-49: `1.0.0-rc1`-`1.0.0-rc25`
  46   - 50: `1.0.0`
  47   - 51-99: `1.0.0-1`-`1.0.0-49`
  48   - (`CLIENT_VERSION_REVISION` rolls over)
  49   - 0-24: `1.0.1-beta1`-`1.0.1-beta25`
  50
  51 - Change `CLIENT_VERSION_IS_RELEASE` to false while Zcash is in beta-test phase.
  52
  53 If this release changes the behavior of the protocol or fixes a serious bug, we may
  54 also wish to change the `PROTOCOL_VERSION` in `version.h`.
  55
  56 Commit these changes. (Be sure to do this before building, or else the built binary will include the flag `-dirty`)
  57
  58 Build by running `./zcutil/build.sh`.
  59
  60 Then perform the following command:
  61
  62     $ bash contrib/devtools/gen-manpages.sh
  63
  64 Commit the changes.
  65
  66 ### B2. Write release notes
  67
  68 Run the release-notes.py script to generate release notes and update authors.md file. For example:
  69
  70     $ python zcutil/release-notes.py --version $ZCASH_RELEASE
  71
  72 Add the newly created release notes to the Git repository:
  73
  74     $ git add doc/release-notes/release-notes-$ZCASH_RELEASE.md
  75
  76 Update the Debian package changelog:
  77
  78     export DEBVERSION="${ZCASH_RELEASE}"
  79     export DEBEMAIL="${DEBEMAIL:[email protected]}"
  80     export DEBFULLNAME="${DEBFULLNAME:-Zcash Company}"
  81
  82     dch -v $DEBVERSION -D jessie -c contrib/debian/changelog
  83
  84 (`dch` comes from the devscripts package.)
  85
  86 ### B3. Change the network magics
  87
  88 If this release breaks backwards compatibility, change the network magic
  89 numbers. Set the four `pchMessageStart` in `CTestNetParams` in `chainparams.cpp`
  90 to random values.
  91
  92 ### B4. Merge the previous changes
  93
  94 Do the normal pull-request, review, testing process for this release PR.
  95
  96 ## C. Verify code artifact hosting
  97
  98 ### C1. Ensure depends tree is working
  99
 100 https://ci.z.cash/builders/depends-sources
 101
 102 ### C2. Ensure public parameters work
 103
 104 Run `./fetch-params.sh`.
 105
 106 ## D. Make tag for the newly merged result
 107
 108 Checkout master and pull the latest version to ensure master is up to date with the release PR which was merged in before.
 109
 110 Check the last commit on the local and remote versions of master to make sure they are the same.
 111
 112 Then create the git tag:
 113
 114     $ git tag -s v${ZCASH_RELEASE}
 115     $ git push origin v${ZCASH_RELEASE}
 116
 117 ## E. Deploy testnet
 118
 119 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:
 120
 121 * builds Zcash based on the specified branch
 122 * deploys it as a public service (e.g. betatestnet.z.cash, mainnet.z.cash)
 123 * 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
 124 * possible manual steps: blowing away the `testnet3` dir, deleting old parameters, restarting DNS seeder
 125
 126 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.
 127
 128 ## F. Update the 1.0 User Guide
 129
 130 ## G. Publish the release announcement (blog, zcash-dev, slack)
 131
 132 ### G1. Check in with users who opened issues that were resolved in the release
 133
 134 Contact all users who opened `user support` issues that were resolved in the release, and ask them if the release fixes or improves their issue.
 135
 136 ## H. Make and deploy deterministic builds
 137
 138 - Run the [Gitian deterministic build environment](https://github.com/zcash/zcash-gitian)
 139 - Compare the uploaded [build manifests on gitian.sigs](https://github.com/zcash/gitian.sigs)
 140 - If all is well, the DevOps engineer will build the Debian packages and update the
 141   [apt.z.cash package repository](https://apt.z.cash).
 142
 143 ## I. Celebrate
 144
 145 ## missing steps
 146 Zcash still needs:
 147
 148 * thorough pre-release testing (presumably more thorough than standard PR tests)
 149
 150 * automated release deployment (e.g.: updating build-depends mirror, deploying testnet, etc...)