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     doc/README.md
  36     src/clientversion.h
  37     configure.ac
  38     contrib/DEBIAN/control
  39     contrib/gitian-descriptors/gitian-linux.yml
  40
  41
  42 In `configure.ac` and `clientversion.h`:
  43
  44 - Increment `CLIENT_VERSION_BUILD` according to the following schema:
  45
  46   - 0-24: `1.0.0-beta1`-`1.0.0-beta25`
  47   - 25-49: `1.0.0-rc1`-`1.0.0-rc25`
  48   - 50: `1.0.0`
  49   - 51-99: `1.0.0-1`-`1.0.0-49`
  50   - (`CLIENT_VERSION_REVISION` rolls over)
  51   - 0-24: `1.0.1-beta1`-`1.0.1-beta25`
  52
  53 - Change `CLIENT_VERSION_IS_RELEASE` to false while Zcash is in beta-test phase.
  54
  55 ### B2. write release notes
  56
  57 git shortlog helps a lot, for example:
  58
  59     $ git shortlog --no-merges v${ZCASH_RELEASE_PREV}..HEAD \
  60         > ./doc/release-notes/release-notes-${ZCASH_RELEASE}.md
  61
  62 Update the Debian package changelog:
  63
  64     export DEBVERSION='1.0.0-rc1'
  65     export DEBEMAIL="${DEBEMAIL:[email protected]}"
  66     export DEBFULLNAME="${DEBFULLNAME:-Zcash Company}"
  67
  68     dch -v $DEBVERSION -D jessie -c contrib/DEBIAN/changelog
  69
  70 ### B3. change the network magics
  71
  72 If this release breaks backwards compatibility, change the network magic
  73 numbers. Set the four `pchMessageStart` in `CTestNetParams` in `chainparams.cpp`
  74 to random values.
  75
  76 ### B4. merge the previous changes
  77
  78 Do the normal pull-request, review, testing process for this release PR.
  79
  80 ## C. Verify code artifact hosting
  81
  82 ### C1. Ensure depends tree is working
  83
  84 https://ci.z.cash/builders/depends-sources
  85
  86 ### C2. Ensure public parameters work
  87
  88 Run `./fetch-params.sh`.
  89
  90 ## D. make tag for the newly merged result
  91
  92 In this example, we ensure master is up to date with the
  93 previous merged PR, then:
  94
  95     $ git tag -s v${ZCASH_RELEASE}
  96     $ git push origin v${ZCASH_RELEASE}
  97
  98 ## E. deploy testnet
  99
 100 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:
 101
 102 * builds Zcash based on the specified branch
 103 * deploys it as a public service (e.g. betatestnet.z.cash, mainnet.z.cash)
 104 * 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
 105 * possible manual steps: blowing away the `testnet3` dir, deleting old parameters, restarting DNS seeder
 106
 107 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.
 108
 109 ## F. publish the release announcement (blog, zcash-dev, slack)
 110 ## G. celebrate
 111 ## missing steps
 112 Zcash still needs:
 113
 114 * deterministic or reproducible builds
 115
 116 * thorough pre-release testing (presumably more thorough than standard PR tests)
 117
 118 * release deployment steps (eg: updating build-depends mirror, deploying testnet, etc...)
 119
 120 * proper Zcash-specific versions and names in software and documentation.