Note
|
This document is meant primarily for Gerrit maintainers who have been given approval and submit status to the Gerrit projects. Additionally, maintainers should be given owner status to the Gerrit web site. |
To make a Gerrit release involves a great deal of complex tasks and it is easy to miss a step so this document should hopefully serve as both a how to for those new to the process and as a checklist for those already familiar with these tasks.
Gerrit Release Type
Here are some guidelines on release approaches depending on the
type of release you want to make (stable-fix
, stable
, rc0
,
rc1
…).
Stable
A stable
release is generally built from the master
branch and may
need to undergo some stabilization before releasing the final release.
-
Propose the release with any plans/objectives to the mailing list.
-
Release plans usually become a news article to be followed up with.
-
Create a Gerrit
rc0
. -
If needed create Gerrit
rc1
,rc2
andrc3
(one per week, on Mondays or so; see past release plans).
Note
|
You may let in a few features to these releases. |
-
If needed create a Gerrit
rc4
.
Note
|
There should be no new features in this release, only bug fixes. |
-
Finally create the
stable
release (norc
).
Stable-Fix
stable-fix
releases should likely only contain bug fixes and doc
updates.
-
Propose the release with any plans/objectives to the mailing list.
-
This type of release does not need any RCs, release when the objectives are met.
Security-Fix
security-fix
releases should only contain bug fixes for security
issues.
For security issues it is important that they are only announced
after fixed versions for all relevant releases have been published.
Because of this, security-fix
releases can’t be prepared in the public
gerrit
project.
security-fix
releases are prepared in the gerrit-security-fixes
project which is only readable by the Gerrit Maintainers. Only after
a security-fix
release has been published will the commits/tags made in
the gerrit-security-fixes
project be taken over into the public
gerrit
project.
Upload the final Release Notes change
Upload a change on the homepage project to:
-
Remove 'In Development' caveat from the relevant section.
-
Add links to the released documentation and the .war file, and make the latest version bold.
The uploaded change is not to be approved yet, but rather act as the release content review thread until it can be finalized.
Update homepage links
Upload a change on the homepage project to change the version numbers to the new version.
Link fixed issues in the Release Notes
Link the fixed issues by hand. There is no script for this.
All issues that are listed in commit messages since the previous version tag have been fixed in the new release and should be linked in the release notes.
In addition the fixed issues should be added to the corresponding
FixedIn-$version
hotlist. Ideally issues are already added to this hotlist at
the moment when a fix is submitted and the status of the issue is set to
Fixed
, but people may forget about this. Hence check whether there are issues
that need to be added to this hotlist.
Note
|
If you create a new hotlist for a release add it to this bookmark group so that people can find it easily. |
Mention each issue that has been fixed in the release in the uploaded change, following the examples from the previous version notes. Optionally, add the issue owners as reviewers to the uploaded change. More reviewers can be added or cc’ed, to further coordinate the final release contents.
Similarly to issues, also mention every noteworthy change done after the previous release. Again, previous notes should be used as template examples.
You may need to split note update changes from the final change that updates the links. This allows non-final update changes to be reviewed and submitted timely. The final (links) change may take more time to complete, as this underlying release process unfolds.
Create the Actual Release
There are several steps involved in creating the actual release. In order to minimise room for error, the release should be done by executing a fully automated jenkins job.
The Jenkins job is defined here.
Ideally, for security reasons, it should be run from a node that is unreachable from the internet, is not the local laptop normally used for other purposes and does not receive any data from external sources, such as e-mails or other messages, unless the data is explicitly downloaded as part of the release process. The following credentials must be made available in the Jenkins vault, with the following credential ids.
-
ossrh-staging-api.central.sonatype.com
The userAndPassword
secret populated with the credentials you created following the instructions defined
here
and should be created ad-hoc for the release plan execution and not reused
from previous releases.
NOTE: As soon as the full release plan is complete, the Maven credentials should be destroyed and removed from the Maven portal to minimize the risk of a [supply-chain attack](https://www.sonatype.com/blog/ongoing-npm-software-supply-chain-attack-exposes-new-risks).
-
gerrit.googlesource.com
The userAndPassword
secret populated with the user and password of the git identity that will be used
to read, push and sign tags during the gerrit release.
Note that this user has to match the identity associated to the GPG credentials used for signing.
NOTE: Do not use the maintainer credentials to minimize the collateral damage if these are stolen.
-
gpg-key
A secret
text credentials containing the GPG private key obtained when
generating the GPG key.
It requires the following parameters:
-
GCLOUD_AUTH_TOKEN
the Gcloud authentication token used to upload the gerrit.war and its documentation to gcloud. The Gcloud Auth token is obtained via 'gcloud auth login' and then 'gcloud auth print-access-token'.
-
GPG_PASSPHRASE
The GPG passphrase obtained when generating the GPG key.
-
VERSION Gerrit semantic release number to upgrade to. Example:
3.13.0-rc2
. -
BRANCH Gerrit branch name where the release must be cut from Example:
master
orstable-3.12
. -
NEXT_VERSION: Next SNAPSHOT version after release. Example: 3.12.3-SNAPSHOT
-
MIGRATION_VERSION: The release job will run a test migration from an earlier Gerrit version performing some base smoke tests. Example: 3.12.2
-
To where the artifacts are uploaded depends on the
VERSION
provided as parameter.-
SNAPSHOT versions are directly uploaded into the Sonatype snapshots repository and no further action is needed:
-
Release versions are uploaded into a staging repository in the Sonatype Nexus Server.
-
-
Verify the staging repository
-
Go to the Maven Central Repository and sign in with your Sonatype credentials.
-
In the
Deployment Info
section and you will find thecom.google.gerrit
staging repository. -
Verify its content
While the staging repository is open you can upload further content and also replace uploaded artifacts. If something is wrong with the staging repository you can drop it by selecting it and clicking on
Drop
. -
Run Maven Central validations on the staging repository
Select the staging repository and click on
Publish
. This runs the Maven Central validations on the staging repository. The repository will only be closed if everything is OK. A closed repository cannot be modified anymore, but you may still drop it if you find any issues. -
Test closed staging repository
You can download any artifact from the
Component Summary
section for further testing of the artifacts in this repository, e.g. to try building a plugin against the plugin API in this repository update the version in the*_pom.xml
and configure the repository:<repositories> <repository> <id>gerrit-staging-repository</id> <url>https://oss.sonatype.org/content/repositories/comgooglegerrit-1029</url> </repository> </repositories>
-
-
Release the staging repository
How to release a staging repository is described in the Sonatype OSS Maven Repository Usage Guide.
WarningReleasing artifacts to Maven Central cannot be undone! -
Find the closed staging repository in the Sonatype Nexus Server, select it and click on
Release
. -
The released artifacts are available in https://oss.sonatype.org/content/repositories/releases/com/google/gerrit/.
-
It may take up to 2 hours until the artifacts appear on Maven Central:
-
-
[optional]: View download statistics
-
Sign in to the Sonatype Nexus Server.
-
Click on 'Views/Repositories' in the left navigation bar under 'Central Statistics'.
-
Select
com.google.gerrit
asProject
.
-
Push the Stable Branch
-
Create the stable branch
stable-$version
in thegerrit
project via the Gerrit Web UI or by push. -
Push the commits done on
stable-$version
torefs/for/stable-$version
and get them merged. -
Create a change updating the
defaultbranch
field in the.gitreview
to match the branch name created.
Publish TypeScript Plugin API
Only applies to major and minor releases! Not required for patch releases.
-
Publish a new version of the npm package
@gerritcodereview/typescript-api
. See api/README.md for details. -
The plugins in the stable branch of the minor release and the master branch be changed to use the new API version, see example change
Finalize the Release Notes
Submit any previously uploaded notes change on the homepage project.
Update list of supported releases
If you created a new stable release update the list of supported releases in the support page.
Gerrit releases are also listed on the
endoflife website.
Push a PR to
endoflife.date repository
to update supported releases in products/gerrit.md
. New release tags
should be updated automatically by the site’s automation job which uses
Dependabot to
auto-create PRs
for new release tags.
Announce on Mailing List
Send an email to the mailing list to announce the release. The content of the
announcement email is generated with the release-announcement.py
script from
the gerrit-release-tools repository, which automatically includes all the
necessary links, hash values, and wraps the text in a PGP signature.
For details refer to the documentation in the script’s header, and/or the help text:
~/gerrit-release-tools/release-announcement.py --help
Merge stable
into master
After every release, stable should be merged to master to ensure that none of the changes/fixes ever get lost.
git config merge.summary true git checkout master git reset --hard origin/master git branch -f stable origin/stable git merge stable
Bazlets is used by gerrit plugins to simplify build process. To allow the new released version to be used by gerrit plugins, gerrit_api.bzl must reference the new version. Upload a change to bazlets repository with api version upgrade.
Clean up on master
Once you are done with the release, check if there are any code changes in the master branch that were gated on the next release. Mostly, these are feature-deprecations that we were holding off on to have a stable release where the feature is still contained, but marked as deprecated.
See Deprecating features for details.
Part of Gerrit Code Review