|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 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
If needed create Gerrit
rc3(one per week, on Mondays or so; see past release plans).
|You may let in a few features to these releases.|
If needed create a Gerrit
|There should be no new features in this release, only bug fixes.|
Finally create the
stable-fix releases should likely only contain bug fixes and doc
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 releases should only contain bug fixes for security
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
security-fix releases are prepared in the
project which is only readable by the Gerrit Maintainers. Only after
security-fix release has been published will the commits/tags made in
gerrit-security-fixes project be taken over into the public
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.
Update the Issues
Update the issues by hand. There is no script for this.
Our current process is an issue should be updated to say
Submitted, FixedIn-$version once the change is submitted, but before the
The updated issues are the ones listed in commit messages since the previous version tag. Mention each updated issue in the uploaded change, following the examples from the previous version notes. Add updated issue owners as reviewers of 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
Update Versions and Create Release Tag
Before doing the release build, the
GERRIT_VERSION in the
file must be updated, e.g. change it from
In addition the version must be updated in a number of
To do this run the
./tools/version.py script and provide the new
version as parameter, e.g.:
version=2.15 ./tools/version.py $version
Commit the changes and create a signed release tag on the new commit:
git tag -s -m "v$version" "v$version"
If unable to tag, make sure that git is locally
configured with your user’s key. These are the
macOS instructions but such commands should be portable enough. Setting
GPG_TTY this way or similar might also be necessary:
Tag the plugins:
git submodule foreach '[ "$sm_path" == "modules/jgit" ] || git tag -s -m "v$version" "v$version"'
Build the Gerrit WAR, API JARs and documentation:
bazel build release Documentation:searchfree ./tools/maven/api.sh war_install ./tools/maven/api.sh install
Verify the WAR version:
java -jar bazel-bin/release.war --version
Try upgrading a test site and launching the daemon.
Verify the plugin versions:
java -jar bazel-bin/release.war init --list-plugins
Publish the Gerrit Release
Publish the Gerrit artifacts to Maven Central
Make sure you have done the configuration for deploying to Maven Central.
Make sure that the version is updated in the
version.bzlfile and in the
*_pom.xmlfiles as described in the Update Versions and Create Release Tag section.
Push the WAR to Maven Central:
Push the plugin artifacts to Maven Central:
To where the artifacts are uploaded depends on the
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 Sonatype Nexus Server and sign in with your Sonatype credentials.
Click on 'Build Promotion' in the left navigation bar under 'Staging Repositories' and find the
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
Run Sonatype validations on the staging repository
Select the staging repository and click on
Close. This runs the Sonatype 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
Once a repository is closed you can find the URL to it in the
Summarysection, e.g. https://oss.sonatype.org/content/repositories/comgooglegerrit-1029.
Use this URL 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.xmland 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.Warning
Releasing artifacts to Maven Central cannot be undone!
Find the closed staging repository in the Sonatype Nexus Server, select it and click on
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'.
Publish the Gerrit WAR to the Google Cloud Storage
Go to the gerrit-releases bucket in the Google cloud storage console.
Make sure you are signed in with your Gmail account.
Manually upload the Gerrit WAR file by using the
Push the Stable Branch
Create the stable branch
gerritproject via the Gerrit Web UI or by push.
Push the commits done on
refs/for/stable-$versionand get them merged.
Create a change updating the
defaultbranchfield in the
.gitreviewto match the branch name created.
Push the Release Tag
Push the new Release Tag:
git push gerrit-review tag v$version
Push the new Release Tag on the plugins:
git submodule foreach '[ "$sm_path" == "modules/jgit" ] || git push gerrit-review tag "v$version"'
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
Upload the Documentation
Extract the documentation files from the zip file generated from
bazel build searchfree:
Upload the files manually via web browser to the appropriate folder in the gerrit-documentation storage bucket.
Finalize the Release Notes
Submit any previously uploaded notes change on the homepage project.
Update the Issues
After the release is actually made, you can search (in Monorail) for
Status=Submitted FixedIn=$version and then batch update these changes
Status=Released. Make sure the pulldown says
Status=Submitted is considered a closed issue.
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:
Increase Gerrit Version for Current Development
All new development that is done in the
master branch will be included in the
next Gerrit release. The Gerrit version should be set to the snapshot version
for the next release.
version tool to set the version in the
Verify that the changes made by the tool are sane, then commit them, push the change for review on the master branch, and get it merged.
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