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 ### B2. Write release notes
  60
  61 Run the release-notes.py script to generate release notes and update authors.md file. For example:
  62
  63     $ python zcutil/release-notes.py --version $ZCASH_RELEASE
  64
  65 Update the Debian package changelog:
  66
  67     export DEBVERSION="${ZCASH_RELEASE}"
  68     export DEBEMAIL="${DEBEMAIL:-team@z.cash}"
  69     export DEBFULLNAME="${DEBFULLNAME:-Zcash Company}"
  70
  71     dch -v $DEBVERSION -D jessie -c contrib/DEBIAN/changelog
  72
  73 (`dch` comes from the devscripts package.)
  74
  75 ### B3. Change the network magics
  76
  77 If this release breaks backwards compatibility, change the network magic
  78 numbers. Set the four `pchMessageStart` in `CTestNetParams` in `chainparams.cpp`
  79 to random values.
  80
  81 ### B4. Merge the previous changes
  82
  83 Do the normal pull-request, review, testing process for this release PR.
  84
  85 ## C. Verify code artifact hosting
  86
  87 ### C1. Ensure depends tree is working
  88
  89 https://ci.z.cash/builders/depends-sources
  90
  91 ### C2. Ensure public parameters work
  92
  93 Run `./fetch-params.sh`.
  94
  95 ## D. Make tag for the newly merged result
  96
  97 In this example, we ensure master is up to date with the
  98 previous merged PR, then:
  99
 100     $ git tag -s v${ZCASH_RELEASE}
 101     $ git push origin v${ZCASH_RELEASE}
 102
 103 ## E. Deploy testnet
 104
 105 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:
 106
 107 * builds Zcash based on the specified branch
 108 * deploys it as a public service (e.g. betatestnet.z.cash, mainnet.z.cash)
 109 * 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
 110 * possible manual steps: blowing away the `testnet3` dir, deleting old parameters, restarting DNS seeder
 111
 112 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.
 113
 114 ## F. Update the 1.0 User Guide
 115
 116 ## G. Publish the release announcement (blog, zcash-dev, slack)
 117
 118 ### G1. Check in with users who opened issues that were resolved in the release
 119
 120 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.
 121
 122 ## H. Make and deploy deterministic builds
 123
 124 - Run the [Gitian deterministic build environment](https://github.com/zcash/zcash-gitian)
 125 - Compare the uploaded [build manifests on gitian.sigs](https://github.com/zcash/gitian.sigs)
 126 - If all is well, the DevOps engineer will build the Debian packages and update the
 127   [apt.z.cash package repository](https://apt.z.cash).
 128
 129 ## I. Celebrate
 130
 131 ## missing steps
 132 Zcash still needs:
 133
 134 * thorough pre-release testing (presumably more thorough than standard PR tests)
 135
 136 * automated release deployment (e.g.: updating build-depends mirror, deploying testnet, etc...)