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

  • Create a Gerrit RC0

  • If needed create a Gerrit RC1

Note

You may let in a few features to this release

  • If needed create a Gerrit RC2

Note

There should be no new features in this release, only bug fixes

  • Finally create the stable release (no RC)

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.

Create the Actual Release

To create a Gerrit release the following steps have to be done:

  1. Release Subprojects

  2. Build the Gerrit Release

  3. Publish the Gerrit Release

    1. Publish the Gerrit artifacts to Maven Central

    2. Publish the Gerrit WAR to Google Storage

    3. Push the Stable Branch

    4. Push the Release Tag

    5. Upload the Documentation

    6. Update the Issues

    7. Announce on Mailing List

  4. Increase Gerrit Version for Current Development

  5. Merge stable into master

Release Subprojects

The subprojects to be released are:

  • gwtjsonrpc

  • gwtorm

  • prolog-cafe

For each subproject do:

  • Check the dependency to the Subproject in the Gerrit parent pom.xml:

    If a SNAPSHOT version of the subproject is referenced the subproject needs to be released so that Gerrit can reference a released version of the subproject.

  • Make a snapshot and test it

  • Prepare the Release

  • Publish the Release

  • Update the id, bin_sha1, and src_sha1 values in the maven_jar for the Subproject in /lib/BUCK to the released version.

Update Versions and Create Release Tag

Before doing the release build, the GERRIT_VERSION in the VERSION file must be updated, e.g. change it from 2.5-SNAPSHOT to 2.5.

In addition the version must be updated in a number of pom.xml files.

To do this run the ./tools/version.py script and provide the new version as parameter, e.g.:

  ./tools/version.py 2.5

Also check and update the referenced archetypeVersion and the archetypeRepository in the Documentation/dev-plugins.txt file. If the referenced archetypeVersion will be available in the Maven central, delete the line with the archetypeRepository.

Commit the changes and create the release tag on the new commit:

  git tag -a v2.5

Tag the plugins:

  git submodule foreach git tag -a v2.5

Build Gerrit

  • Build the Gerrit WAR and API JARs

      buck clean
  buck build --no-cache release
  buck build api_install

  • Sanity check WAR

  • Test the new Gerrit version

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 file and in the pom.xml files as described in the Update Versions and Create Release Tag section.

  • Push the WAR to Maven Central:

      buck build war_deploy

  • Push the plugin artifacts to Maven Central:

      buck build api_deploy

    For troubleshooting, the environment variable VERBOSE can be set. This prints out the commands that are executed by the Buck build process:

      VERBOSE=1 buck build api_deploy

    If no artifacts are uploaded, clean the buck-out folder and retry:

      rm -rf buck-out

  • Push the plugin Maven archetypes to Maven Central:

      ./tools/plugin_archetype_deploy.sh

  • To where the artifacts are uploaded depends on the GERRIT_VERSION in the VERSION file:

  • 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 comgooglegerrit-XXXX 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 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 Summary section, 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.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.

    Warning
    		 Releasing artifacts to Maven Central cannot be undone!

  • [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 as Project.

Publish the Gerrit WAR to the Google Cloud Storage

Push the Stable Branch

  • Create the stable branch stable-2.5 in the gerrit project via the Gerrit Web UI or by push.

  • Push the commits done on stable-2.5 to refs/for/stable-2.5 and get them merged

Push the Release Tag

Push the new Release Tag:

  git push gerrit-review tag v2.5

Push the new Release Tag on the plugins:

  git submodule foreach git push gerrit-review tag v2.5

Upload the Documentation

  • Build the release notes:

      make -C ReleaseNotes

  • Build the documentation:

      buck build docs

  • Extract the documentation html files from the generated zip file buck-out/gen/Documentation/searchfree.zip.

  • Upload the html files manually via web browser to the gerrit-documentation storage bucket.

Upload a change on the homepage project to change the version numbers to the new version.

Update the Issues

How do the issues get updated?  Do you run a script to do
this?  When do you do it, after the final 2.5 is released?

By hand.

Our current process is an issue should be updated to say Status = Submitted, FixedIn-2.5 once the change is submitted, but before the release.

After the release is actually made, you can search in Google Code for Status=Submitted FixedIn=2.5'' and then batch update these changes to say Status=Released. Make sure the pulldown says All Issues'' because Status=Submitted is considered a closed issue.

Announce on Mailing List

  • Send an email to the mailing list to announce the release, consider including some or all of the following in the email:

    • A link to the release and the release notes (if a final release)

    • A link to the docs

    • Describe the type of release (stable, bug fix, RC)

  • Add an entry to the NEWS section of the main Gerrit project web page

 * Jun 14, 2012 - Gerrit 2.4.1 [https://groups.google.com/d/topic/repo-discuss/jHg43gixqzs/discussion Released]

  • Update the new discussion group announcement to be sticky

  • Update the previous discussion group announcement to no longer be sticky

    • See above (unclick checkbox)

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.

Use the version tool to set the version in the VERSION file and plugin archetypes' pom.xml files:

 ./tools/version.py 2.11-SNAPSHOT

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.

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

Part of Gerrit Code Review