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     Build and commit to update versions, and then perform the following commands:
  41
  42     help2man -n "RPC client for the Zcash daemon" src/zcash-cli > contrib/DEBIAN/manpages/zcash-cli.1
  43     help2man -n "Network daemon for interacting with the Zcash blockchain" src/zcashd > contrib/DEBIAN/manpages/zcashd.1
  44
  45
  46 In `configure.ac` and `clientversion.h`:
  47
  48 - Increment `CLIENT_VERSION_BUILD` according to the following schema:
  49
  50   - 0-24: `1.0.0-beta1`-`1.0.0-beta25`
  51   - 25-49: `1.0.0-rc1`-`1.0.0-rc25`
  52   - 50: `1.0.0`
  53   - 51-99: `1.0.0-1`-`1.0.0-49`
  54   - (`CLIENT_VERSION_REVISION` rolls over)
  55   - 0-24: `1.0.1-beta1`-`1.0.1-beta25`
  56
  57 - Change `CLIENT_VERSION_IS_RELEASE` to false while Zcash is in beta-test phase.
  58
  59 If this release changes the behavior of the protocol or fixes a serious bug, we may
  60 also wish to change the `PROTOCOL_VERSION` in `version.h`.
  61
  62 ### B2. Write release notes
  63
  64 Run the release-notes.py script to generate release notes and update authors.md file. For example:
  65
  66     $ python zcutil/release-notes.py --version $ZCASH_RELEASE
  67
  68 Update the Debian package changelog:
  69
  70     export DEBVERSION="${ZCASH_RELEASE}"
  71     export DEBEMAIL="${DEBEMAIL:[email protected]}"
  72     export DEBFULLNAME="${DEBFULLNAME:-Zcash Company}"
  73
  74     dch -v $DEBVERSION -D jessie -c contrib/DEBIAN/changelog
  75
  76 (`dch` comes from the devscripts package.)
  77
  78 ### B3. Change the network magics
  79
  80 If this release breaks backwards compatibility, change the network magic
  81 numbers. Set the four `pchMessageStart` in `CTestNetParams` in `chainparams.cpp`
  82 to random values.
  83
  84 ### B4. Merge the previous changes
  85
  86 Do the normal pull-request, review, testing process for this release PR.
  87
  88 ## C. Verify code artifact hosting
  89
  90 ### C1. Ensure depends tree is working
  91
  92 https://ci.z.cash/builders/depends-sources
  93
  94 ### C2. Ensure public parameters work
  95
  96 Run `./fetch-params.sh`.
  97
  98 ## D. Make tag for the newly merged result
  99
 100 In this example, we ensure master is up to date with the
 101 previous merged PR, then:
 102
 103     $ git tag -s v${ZCASH_RELEASE}
 104     $ git push origin v${ZCASH_RELEASE}
 105
 106 ## E. Deploy testnet
 107
 108 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:
 109
 110 * builds Zcash based on the specified branch
 111 * deploys it as a public service (e.g. betatestnet.z.cash, mainnet.z.cash)
 112 * 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
 113 * possible manual steps: blowing away the `testnet3` dir, deleting old parameters, restarting DNS seeder
 114
 115 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.
 116
 117 ## F. Update the 1.0 User Guide
 118
 119 ## G. Publish the release announcement (blog, zcash-dev, slack)
 120
 121 ### G1. Check in with users who opened issues that were resolved in the release
 122
 123 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.
 124
 125 ## H. Make and deploy deterministic builds
 126
 127 - Run the [Gitian deterministic build environment](https://github.com/zcash/zcash-gitian)
 128 - Compare the uploaded [build manifests on gitian.sigs](https://github.com/zcash/gitian.sigs)
 129 - If all is well, the DevOps engineer will build the Debian packages and update the
 130   [apt.z.cash package repository](https://apt.z.cash).
 131
 132 ## I. Celebrate
 133
 134 ## missing steps
 135 Zcash still needs:
 136
 137 * thorough pre-release testing (presumably more thorough than standard PR tests)
 138
 139 * automated release deployment (e.g.: updating build-depends mirror, deploying testnet, etc...)