Update release process documentation to clarify the use of release stabilization branches.
This commit is contained in:
parent
6b80f3ba1f
commit
a5f6af12b8
|
@ -35,7 +35,9 @@ base instead of `master`. Each PR should be reviewed and merged as normal.
|
||||||
## Release process
|
## Release process
|
||||||
|
|
||||||
The majority of this process is identical to the standard release process.
|
The majority of this process is identical to the standard release process.
|
||||||
However, there are a few notable differences:
|
Release candidates for hotfixes should be created and tested as normal, using
|
||||||
|
the `hotfix-<RELEASE>` branch in place of the release stabilization branch,
|
||||||
|
with a couple of minor differences:
|
||||||
|
|
||||||
- When running the release script, use the `--hotfix` flag. Provide the hash of
|
- When running the release script, use the `--hotfix` flag. Provide the hash of
|
||||||
the commit to be released as the first argument:
|
the commit to be released as the first argument:
|
||||||
|
@ -45,17 +47,3 @@ However, there are a few notable differences:
|
||||||
- To review the automated changes in git:
|
- To review the automated changes in git:
|
||||||
|
|
||||||
$ git log hotfix-<RELEASE>..HEAD
|
$ git log hotfix-<RELEASE>..HEAD
|
||||||
|
|
||||||
- After the standard review process, use the hotfix merge process outlined above
|
|
||||||
instead of the regular merge process.
|
|
||||||
|
|
||||||
- When making the tag, check out the hotfix branch instead of master.
|
|
||||||
|
|
||||||
## Post-release
|
|
||||||
|
|
||||||
Once the hotfix release has been created, a new PR should be opened for merging
|
|
||||||
the hotfix release branch into master. This may require fixing merge conflicts
|
|
||||||
(e.g. changing the version number in the hotfix branch to match master, if
|
|
||||||
master is ahead). Such conflicts **MUST** be addressed with additional commits
|
|
||||||
to the hotfix branch; specifically, the branch **MUST NOT** be rebased on
|
|
||||||
master.
|
|
||||||
|
|
|
@ -63,23 +63,47 @@ The release script has the following dependencies:
|
||||||
You can optionally install the `progressbar2` Python module with pip to have a
|
You can optionally install the `progressbar2` Python module with pip to have a
|
||||||
progress bar displayed during the build process.
|
progress bar displayed during the build process.
|
||||||
|
|
||||||
## Release process
|
## Versioning
|
||||||
|
|
||||||
Identify the commit from which the release will be made. This could be the current
|
Zcash version identifiers have the format `vX.Y.Z` with the following conventions:
|
||||||
`HEAD` of `master`, but it's also often useful to instead use a release stabilization
|
|
||||||
branch based upon a previous release candidate when producing a release, so that
|
|
||||||
development can proceed unblocked on the `master` branch during the release candidate
|
|
||||||
testing and bug-fixing process.
|
|
||||||
|
|
||||||
In the commands below, <RELEASE> and <RELEASE_PREV> must be prefixed with a v, i.e. v1.0.9
|
* Increments to the `X` component (the "major version") correspond to network
|
||||||
(not 1.0.9). <COMMIT_ID> is the `git` hash identifying the commit on which the release
|
upgrades. A network upgrade occurs only when there is a change to the
|
||||||
branch will be based. It is recommended to use the entire hash value to identify the
|
consensus rules.
|
||||||
commit, although a prefix of at least 10 characters is also permitted.
|
* Increments to the `Y` component (the "minor version") correspond to regular
|
||||||
|
Zcash releases. These occur approximately every 6 weeks and may include breaking
|
||||||
|
changes to public APIs.
|
||||||
|
* Increments to the `Z` component occur only in the case of hotfix releases.
|
||||||
|
|
||||||
### Create the release branch
|
## Release candidate & release process
|
||||||
|
|
||||||
Run the release script, which will create a branch based upon the specified commit ID,
|
Identify the commit from which the release stabilization branch will be made.
|
||||||
then commit standard automated changes to that branch locally:
|
Release stabilization branches are used so that development can proceed
|
||||||
|
unblocked on the `master` branch during the release candidate testing and
|
||||||
|
bug-fixing process. By convention, release stabilization branches are named
|
||||||
|
`version-X.Y.0` where `X` and `Y` are the major and minor versions for the
|
||||||
|
release.
|
||||||
|
|
||||||
|
In the commands below, <RELEASE> and <RELEASE_PREV> must identify `git` tags
|
||||||
|
prefixed with the character `v`, i.e. `v1.0.9` (not `1.0.9`). <COMMIT_ID> is a
|
||||||
|
`git` hash identifying the commit on which a release stabilization or release
|
||||||
|
branch will be based. It is recommended to use the entire hash value to
|
||||||
|
identify the commit, although a prefix of at least 10 characters is also
|
||||||
|
permitted.
|
||||||
|
|
||||||
|
### Create the release stabilization branch
|
||||||
|
|
||||||
|
Having identified the commit from which the release will be made, the release
|
||||||
|
manager constructs the release stabilization branch as follows:
|
||||||
|
|
||||||
|
$ git checkout -b version-X.Y.0 <COMMIT_ID>
|
||||||
|
$ git push 'git@github.com:zcash/zcash' $(git rev-parse --abrev-ref HEAD)
|
||||||
|
|
||||||
|
### Create the release candidate branch
|
||||||
|
|
||||||
|
Run the release script to create the first release candidate. This will create
|
||||||
|
a branch based upon the specified commit ID, then commit standard automated
|
||||||
|
changes to that branch locally:
|
||||||
|
|
||||||
$ ./zcutil/make-release.py <COMMIT_ID> <RELEASE> <RELEASE_PREV> <RELEASE_FROM> <APPROX_RELEASE_HEIGHT>
|
$ ./zcutil/make-release.py <COMMIT_ID> <RELEASE> <RELEASE_PREV> <RELEASE_FROM> <APPROX_RELEASE_HEIGHT>
|
||||||
|
|
||||||
|
@ -92,37 +116,52 @@ Examples:
|
||||||
|
|
||||||
Review the automated changes in git:
|
Review the automated changes in git:
|
||||||
|
|
||||||
$ git log master..HEAD
|
$ git log version-X.Y.0..HEAD
|
||||||
|
|
||||||
Push the resulting branch to github:
|
Push the resulting branch to github:
|
||||||
|
|
||||||
$ git push 'git@github.com:$YOUR_GITHUB_NAME/zcash' $(git rev-parse --abbrev-ref HEAD)
|
$ git push 'git@github.com:$YOUR_GITHUB_NAME/zcash' $(git rev-parse --abbrev-ref HEAD)
|
||||||
|
|
||||||
Then create the PR on github. Complete the standard review process and wait
|
Then create the PR on github targeting the `version-X.Y.0` branch. Complete the
|
||||||
for CI to complete.
|
standard review process and wait for CI to complete.
|
||||||
|
|
||||||
## Make tag for the the tip of the release branch
|
## Make a tag for the tip of the release candidate branch
|
||||||
|
|
||||||
NOTE: This has changed from the previously recommended process. The tag should be created
|
NOTE: This has changed from the previously recommended process. The tag should
|
||||||
at the tip of the release branch; this ensures that any changes made to the `master`
|
be created at the tip of the automatically-generated release branch created by
|
||||||
branch since the initiation of the release process are not accidentally tagged as being
|
the release script; this ensures that any changes made to the release
|
||||||
part of the release as a consequence of having been included in a merge commit.
|
stabilization branch since the initiation of the release process are not
|
||||||
|
accidentally tagged as being part of the release as a consequence of having
|
||||||
|
been included in a merge commit.
|
||||||
|
|
||||||
Check the last commit on the local and remote versions of the release branch to make sure
|
Check the last commit on the local and remote versions of the release branch to
|
||||||
they are the same:
|
make sure they are the same:
|
||||||
|
|
||||||
$ git log -1
|
$ git log -1
|
||||||
|
|
||||||
If you haven't previously done so, set the gpg key id you intend to use for signing:
|
If you haven't previously done so, set the gpg key id you intend to use for
|
||||||
|
signing:
|
||||||
|
|
||||||
git config --global user.signingkey <keyid>
|
git config --global user.signingkey <keyid>
|
||||||
|
|
||||||
Then create the git tag. The `-s` means the release tag will be signed.
|
Then create the git tag. The `-s` means the release tag will be signed. Enter
|
||||||
Enter "Release <version>." and save when prompted for a commit message.
|
"Release <version>." and save when prompted for a commit message. **CAUTION:**
|
||||||
**CAUTION:** Remember the `v` at the beginning here:
|
Remember the `v` at the beginning here:
|
||||||
|
|
||||||
$ git tag -s v1.1.0
|
$ git tag -s vX.Y.Z-rcN
|
||||||
$ git push origin v1.1.0
|
$ git push origin vX.Y.Z-rcN
|
||||||
|
|
||||||
|
## Merge the release candidate branch to the release stabilization branch
|
||||||
|
|
||||||
|
Once CI has completed and the release candidate branch has sufficient approving
|
||||||
|
reviews, merge the release candidate branch back to the release stabilization
|
||||||
|
branch. Testing proceeds as normal. Any changes that need to be made during the
|
||||||
|
release candidate period are made by submitting PRs targeting the release
|
||||||
|
stabilization branch.
|
||||||
|
|
||||||
|
Subsequent release candidates, and the creation of the final release, follow
|
||||||
|
the same process as for release candidates, omitting the `-rcN` suffix for the
|
||||||
|
final release.
|
||||||
|
|
||||||
## Make and deploy deterministic builds
|
## Make and deploy deterministic builds
|
||||||
|
|
||||||
|
@ -149,10 +188,18 @@ the marking to see what GitHub wants to be done.
|
||||||
|
|
||||||
## Post Release Task List
|
## Post Release Task List
|
||||||
|
|
||||||
### Merge the release branch
|
### Merge the release stabilization branch
|
||||||
|
|
||||||
Merge the release branch back to `master` to ensure that any changes made during
|
Once the final release branch has merged to the release stabilization branch, a
|
||||||
release stabilization are reflected in the master branch's history.
|
new PR should be opened for merging the release stabilization branch into
|
||||||
|
master. This may require fixing merge conflicts (e.g. changing the version
|
||||||
|
number in the release stabilization branch to match master, if master is
|
||||||
|
ahead). Such conflicts **MUST** be addressed with additional commits to the
|
||||||
|
release stabilization branch; specifically, the branch **MUST NOT** be rebased
|
||||||
|
on master.
|
||||||
|
|
||||||
|
Once any conflicts have been resolved, the release stabilization branch should
|
||||||
|
be merged back to the `master` branch, and then deleted.
|
||||||
|
|
||||||
### Deploy testnet
|
### Deploy testnet
|
||||||
|
|
||||||
|
|
|
@ -488,7 +488,7 @@ def sh_progress(markers, *args):
|
||||||
class GitHash (object):
|
class GitHash (object):
|
||||||
'''A git commit hash.'''
|
'''A git commit hash.'''
|
||||||
RGX = re.compile(
|
RGX = re.compile(
|
||||||
r'^([0-9a-f]{8,40})$',
|
r'^([0-9a-f]{10,40})$',
|
||||||
)
|
)
|
||||||
|
|
||||||
@staticmethod
|
@staticmethod
|
||||||
|
|
Loading…
Reference in New Issue