Update release process documentation to clarify the use of release stabilization branches.
This commit is contained in:
Kris Nuttycombe
parent
6b80f3ba1f
commit
a5f6af12b8
|
|
@ -35,7 +35,9 @@ base instead of `master`. Each PR should be reviewed and merged as normal.
|
|||
## 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
|
||||
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:
|
||||
|
||||
$ 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
|
||||
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
|
||||
`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.
|
||||
Zcash version identifiers have the format `vX.Y.Z` with the following conventions:
|
||||
|
||||
In the commands below, <RELEASE> and <RELEASE_PREV> must be prefixed with a v, i.e. v1.0.9
|
||||
(not 1.0.9). <COMMIT_ID> is the `git` hash identifying the commit on which the 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.
|
||||
* Increments to the `X` component (the "major version") correspond to network
|
||||
upgrades. A network upgrade occurs only when there is a change to the
|
||||
consensus rules.
|
||||
* 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,
|
||||
then commit standard automated changes to that branch locally:
|
||||
Identify the commit from which the release stabilization branch will be made.
|
||||
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>
|
||||
|
||||
|
|
@ -92,37 +116,52 @@ Examples:
|
|||
|
||||
Review the automated changes in git:
|
||||
|
||||
$ git log master..HEAD
|
||||
$ git log version-X.Y.0..HEAD
|
||||
|
||||
Push the resulting branch to github:
|
||||
|
||||
$ 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
|
||||
for CI to complete.
|
||||
Then create the PR on github targeting the `version-X.Y.0` branch. Complete the
|
||||
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
|
||||
at the tip of the release branch; this ensures that any changes made to the `master`
|
||||
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.
|
||||
NOTE: This has changed from the previously recommended process. The tag should
|
||||
be created at the tip of the automatically-generated release branch created by
|
||||
the release script; this ensures that any changes made to the release
|
||||
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
|
||||
they are the same:
|
||||
Check the last commit on the local and remote versions of the release branch to
|
||||
make sure they are the same:
|
||||
|
||||
$ 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>
|
||||
|
||||
Then create the git tag. The `-s` means the release tag will be signed.
|
||||
Enter "Release <version>." and save when prompted for a commit message.
|
||||
**CAUTION:** Remember the `v` at the beginning here:
|
||||
Then create the git tag. The `-s` means the release tag will be signed. Enter
|
||||
"Release <version>." and save when prompted for a commit message. **CAUTION:**
|
||||
Remember the `v` at the beginning here:
|
||||
|
||||
$ git tag -s v1.1.0
|
||||
$ git push origin v1.1.0
|
||||
$ git tag -s vX.Y.Z-rcN
|
||||
$ 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
|
||||
|
||||
|
|
@ -149,10 +188,18 @@ the marking to see what GitHub wants to be done.
|
|||
|
||||
## 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
|
||||
release stabilization are reflected in the master branch's history.
|
||||
Once the final release branch has merged to the release stabilization branch, a
|
||||
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
|
||||
|
||||
|
|
|
|||
|
|
@ -488,7 +488,7 @@ def sh_progress(markers, *args):
|
|||
class GitHash (object):
|
||||
'''A git commit hash.'''
|
||||
RGX = re.compile(
|
||||
r'^([0-9a-f]{8,40})$',
|
||||
r'^([0-9a-f]{10,40})$',
|
||||
)
|
||||
|
||||
@staticmethod
|
||||
|
|
|
|||
Loading…
Reference in New Issue