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 The following should have been checked well in advance of the release:
   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
  20 ## Release process
  21
  22 ## A. Define the release version as:
  23
  24     $ ZCASH_RELEASE=MAJOR.MINOR.REVISION(-BUILD_STRING)
  25
  26 Example:
  27
  28     $ ZCASH_RELEASE=1.0.0-beta2
  29
  30 Also, the following commands use the `ZCASH_RELEASE_PREV` bash variable for the
  31 previous release:
  32
  33     $ ZCASH_RELEASE_PREV=1.0.0-beta1
  34
  35 ## B. Create a new release branch / github PR
  36
  37 ### B1. Check that you are up-to-date with current master, then create a release branch.
  38
  39 ### B2. Update (commit) version in sources.
  40
  41     README.md
  42     src/clientversion.h
  43     configure.ac
  44     contrib/gitian-descriptors/gitian-linux.yml
  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 Commit these changes. (Be sure to do this before building, or else the built binary will include the flag `-dirty`)
  63
  64 Build by running `./zcutil/build.sh`.
  65
  66 Then perform the following command:
  67
  68     $ bash contrib/devtools/gen-manpages.sh
  69
  70 Commit the changes.
  71
  72 ### B3. Generate release notes
  73
  74 Run the release-notes.py script to generate release notes and update authors.md file. For example:
  75
  76     $ python zcutil/release-notes.py --version $ZCASH_RELEASE
  77
  78 Add the newly created release notes to the Git repository:
  79
  80     $ git add doc/release-notes/release-notes-$ZCASH_RELEASE.md
  81
  82 Update the Debian package changelog:
  83
  84     export DEBVERSION="${ZCASH_RELEASE}"
  85     export DEBEMAIL="${DEBEMAIL:[email protected]}"
  86     export DEBFULLNAME="${DEBFULLNAME:-Zcash Company}"
  87
  88     dch -v $DEBVERSION -D jessie -c contrib/debian/changelog
  89
  90 (`dch` comes from the devscripts package.)
  91
  92 ### B4. Change the network magics
  93
  94 If this release breaks backwards compatibility, change the network magic
  95 numbers. Set the four `pchMessageStart` in `CTestNetParams` in `chainparams.cpp`
  96 to random values.
  97
  98 ### B5. Merge the previous changes
  99
 100 Do the normal pull-request, review, testing process for this release PR.
 101
 102 ## C. Verify code artifact hosting
 103
 104 ### C1. Ensure depends tree is working
 105
 106 https://ci.z.cash/builders/depends-sources
 107
 108 ### C2. Ensure public parameters work
 109
 110 Run `./fetch-params.sh`.
 111
 112 ## D. Make tag for the newly merged result
 113
 114 Checkout master and pull the latest version to ensure master is up to date with the release PR which was merged in before.
 115
 116 Check the last commit on the local and remote versions of master to make sure they are the same.
 117
 118 Then create the git tag:
 119
 120     $ git tag -s v${ZCASH_RELEASE}
 121     $ git push origin v${ZCASH_RELEASE}
 122
 123 ## E. Deploy testnet
 124
 125 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:
 126
 127 * builds Zcash based on the specified branch
 128 * deploys it as a public service (e.g. betatestnet.z.cash, mainnet.z.cash)
 129 * 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
 130 * possible manual steps: blowing away the `testnet3` dir, deleting old parameters, restarting DNS seeder
 131
 132 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.
 133
 134 ## F. Update the 1.0 User Guide
 135
 136 ## G. Publish the release announcement (blog, zcash-dev, slack)
 137
 138 ### G1. Check in with users who opened issues that were resolved in the release
 139
 140 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.
 141
 142 ## H. Make and deploy deterministic builds
 143
 144 - Run the [Gitian deterministic build environment](https://github.com/zcash/zcash-gitian)
 145 - Compare the uploaded [build manifests on gitian.sigs](https://github.com/zcash/gitian.sigs)
 146 - If all is well, the DevOps engineer will build the Debian packages and update the
 147   [apt.z.cash package repository](https://apt.z.cash).
 148
 149 ## I. Celebrate
 150
 151 ## missing steps
 152 Zcash still needs:
 153
 154 * thorough pre-release testing (presumably more thorough than standard PR tests)
 155
 156 * automated release deployment (e.g.: updating build-depends mirror, deploying testnet, etc...)