diff --git a/doc/release-process.md b/doc/release-process.md index d681040f7..8299bf6e4 100644 --- a/doc/release-process.md +++ b/doc/release-process.md @@ -4,26 +4,45 @@ Meta: There should always be a single release engineer to disambiguate responsib ## Pre-release -The following should have been checked well in advance of the release: +### Github Milestone -- All dependencies have been updated as appropriate: - - BDB - - Boost - - ccache - - libgmp - - libsnark (upstream of our fork) - - libsodium - - miniupnpc - - OpenSSL +Ensure all goals for the github milestone are met. If not, remove tickets +or PRs with a comment as to why it is not included. (Running out of time +is a common reason.) + +### Pre-release checklist: + +Check that dependencies are properly hosted by looking at the `check-depends` builder: + + https://ci.z.cash/#/builders/1 + +Check that there are no surprising performance regressions: + + https://speed.z.cash + +Ensure that new performance metrics appear on that site. + +### Protocol Safety Checks: If this release changes the behavior of the protocol or fixes a serious bug, verify that a pre-release PR merge updated `PROTOCOL_VERSION` in `version.h` correctly. +If this release breaks backwards compatibility or needs to prevent +interaction with software forked projects, change the network magic +numbers. Set the four `pchMessageStart` in `CTestNetParams` in +`chainparams.cpp` to random values. + +Both of these should be done in standard PRs ahead of the release +process. If these were not anticipated correctly, this could block the +release, so if you suspect this is necessary, double check with the +whole engineering team. ## Release process -Run the release script: +Run the release script, which will verify you are on the latest clean +checkout of master, create a branch, then commit standard automated +changes to that branch locally: $ ./zcutil/make-release.py @@ -31,58 +50,50 @@ Example: $ ./zcutil/make-release.py v1.0.8-1 v1.0.9 -### B3. Generate release notes +### Create, Review, and Merge the release branch pull request -Run the release-notes.py script to generate release notes and update authors.md file. For example: +Review the automated changes in git: - $ python zcutil/release-notes.py --version $ZCASH_RELEASE + $ git log master..HEAD -Add the newly created release notes to the Git repository: +Push the resulting branch to github: - $ git add ./doc/authors.md ./doc/release-notes/release-notes-$ZCASH_RELEASE.md + $ git push 'git@github.com:$YOUR_GITHUB_NAME/zcash' $(git rev-parse --abbrev-ref HEAD) -Update the Debian package changelog: +Then create the PR on github. Complete the standard review process, +then merge, then wait for CI to complete. - export DEBVERSION=$(echo $ZCASH_RELEASE | sed 's/-beta/~beta/' | sed 's/-rc/~rc/' | sed 's/-/+/') - export DEBEMAIL="${DEBEMAIL:-team@z.cash}" - export DEBFULLNAME="${DEBFULLNAME:-Zcash Company}" - - dch -v $DEBVERSION -D jessie -c contrib/debian/changelog - -(`dch` comes from the devscripts package.) - -### B4. Change the network magics - -If this release breaks backwards compatibility, change the network magic -numbers. Set the four `pchMessageStart` in `CTestNetParams` in `chainparams.cpp` -to random values. - -### B5. Merge the previous changes - -Do the normal pull-request, review, testing process for this release PR. - -## C. Verify code artifact hosting - -### C1. Ensure depends tree is working - -https://ci.z.cash/builders/depends-sources - -### C2. Ensure public parameters work - -Run `./fetch-params.sh`. - -## D. Make tag for the newly merged result +## Make tag for the newly merged result Checkout master and pull the latest version to ensure master is up to date with the release PR which was merged in before. -Check the last commit on the local and remote versions of master to make sure they are the same. + $ git checkout master + $ git pull --ff-only -Then create the git tag: +Check the last commit on the local and remote versions of master to make sure they are the same: - $ git tag -s v${ZCASH_RELEASE} - $ git push origin v${ZCASH_RELEASE} + $ git log -1 -## E. Deploy testnet +The output should include something like, which is created by Homu: + + Auto merge of #4242 - nathan-at-least:release-v1.0.9, r=nathan-at-least + +Then create the git tag. The `-s` means the release tag will be +signed. **CAUTION:** Remember the `v` at the beginning here: + + $ git tag -s v1.0.9 + $ git push origin v1.0.9 + +## Make and deploy deterministic builds + +- Run the [Gitian deterministic build environment](https://github.com/zcash/zcash-gitian) +- Compare the uploaded [build manifests on gitian.sigs](https://github.com/zcash/gitian.sigs) +- If all is well, the DevOps engineer will build the Debian packages and update the + [apt.z.cash package repository](https://apt.z.cash). + +## Post Release Task List + +### Deploy testnet 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: @@ -93,26 +104,8 @@ Notify the Zcash DevOps engineer/sysadmin that the release has been tagged. They 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. -## F. Update the 1.0 User Guide +### Update the 1.0 User Guide -## G. Publish the release announcement (blog, zcash-dev, slack) +### Publish the release announcement (blog, zcash-dev, slack) -### G1. Check in with users who opened issues that were resolved in the release - -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. - -## H. Make and deploy deterministic builds - -- Run the [Gitian deterministic build environment](https://github.com/zcash/zcash-gitian) -- Compare the uploaded [build manifests on gitian.sigs](https://github.com/zcash/gitian.sigs) -- If all is well, the DevOps engineer will build the Debian packages and update the - [apt.z.cash package repository](https://apt.z.cash). - -## I. Celebrate - -## missing steps -Zcash still needs: - -* thorough pre-release testing (presumably more thorough than standard PR tests) - -* automated release deployment (e.g.: updating build-depends mirror, deploying testnet, etc...) +## Celebrate diff --git a/zcutil/make-release.py b/zcutil/make-release.py index 40151b70c..0ea2b3bac 100755 --- a/zcutil/make-release.py +++ b/zcutil/make-release.py @@ -74,7 +74,9 @@ def main_logged(release, releaseprev, releaseheight): gen_manpages() commit('Updated manpages.') - raise NotImplementedError(main_logged) + gen_release_notes(release) + update_debian_changelog(release) + commit('Updated release notes and changelog.') def phase(message): @@ -173,6 +175,30 @@ def gen_manpages(): sh_log('./contrib/devtools/gen-manpages.sh') +@phase('Generating release notes.') +def gen_release_notes(release): + sh_log('python', './zcutil/release-notes.py', '--version', release.novtext) + sh_log( + 'git', + 'add', + './doc/authors.md', + './doc/release-notes/release-notes-{}.md'.format(release.novtext), + ) + + +@phase('Updating debian changelog.') +def update_debian_changelog(release): + os.environ['DEBEMAIL'] = 'team@z.cash' + os.environ['DEBFULLNAME'] = 'Zcash Company' + sh_log( + 'debchange', + '--newversion', release.debversion, + '--distribution', 'stable', + '--changelog', './contrib/debian/changelog', + '{} release.'.format(release.novtext), + ) + + # Helper code: def commit(message): logging.info('Committing: %r', message) @@ -280,7 +306,7 @@ def sh_out(*args): def sh_log(*args): PIPE = subprocess.PIPE try: - p = subprocess.Popen(args, stdout=PIPE, stderr=PIPE) + p = subprocess.Popen(args, stdout=PIPE, stderr=PIPE, stdin=None) except OSError: logging.error('Error launching %r...', args) raise @@ -334,8 +360,6 @@ class Version (object): self.betarc = betarc self.hotfix = hotfix - self.novtext = '{}.{}.{}'.format(major, minor, patch) - if hotfix is None: self.build = 50 else: @@ -343,13 +367,42 @@ class Version (object): if betarc is None: assert hotfix < 50, hotfix self.build = 50 + hotfix - self.novtext += '-{}'.format(hotfix) else: assert hotfix < 26, hotfix - self.novtext += '-{}{}'.format(betarc, hotfix) self.build = {'beta': 0, 'rc': 25}[betarc] + hotfix - 1 - self.vtext = 'v' + self.novtext + @property + def novtext(self): + return self._novtext(debian=False) + + @property + def vtext(self): + return 'v' + self.novtext + + @property + def debversion(self): + return self._novtext(debian=True) + + def _novtext(self, debian): + novtext = '{}.{}.{}'.format(self.major, self.minor, self.patch) + + if self.hotfix is None: + return novtext + else: + assert self.hotfix > 0, self.hotfix + if self.betarc is None: + assert self.hotfix < 50, self.hotfix + sep = '+' if debian else '-' + return '{}{}{}'.format(novtext, sep, self.hotfix) + else: + assert self.hotfix < 26, self.hotfix + sep = '~' if debian else '-' + return '{}{}{}{}'.format( + novtext, + sep, + self.betarc, + self.hotfix, + ) def __repr__(self): return ''.format(self.vtext) diff --git a/zcutil/release-notes.py b/zcutil/release-notes.py old mode 100644 new mode 100755