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