| = Making a Gerrit Release |
| |
| [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]] |
| === 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 |
| link:https://www.gerritcodereview.com/news.html[news article] |
| to be followed up with. |
| |
| * Create a Gerrit `rc0`. |
| |
| * If needed create Gerrit `rc1`, `rc2` and `rc3` (one per week, on Mondays |
| or so; see link:https://www.gerritcodereview.com/news.html[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 (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]] |
| === 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-final-release-notes]] |
| == 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-links]] |
| === Update homepage links |
| |
| Upload a change on the link:https://gerrit-review.googlesource.com/admin/repos/homepage[ |
| homepage project] to change the version numbers to the new version. |
| |
| [[update-issues]] |
| === 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 `Status = |
| Submitted, FixedIn-$version` once the change is submitted, but before the |
| release. |
| |
| 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]] |
| === Update Versions and Create Release Tag |
| |
| Before doing the release build, the `GERRIT_VERSION` in the `version.bzl` |
| file must be updated, e.g. change it from `$version-SNAPSHOT` to `$version`. |
| |
| 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.: |
| |
| ---- |
| 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 |
| link:https://medium.com/@rwbutler/signing-commits-using-gpg-on-macos-7210362d15[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: |
| |
| ---- |
| export GPG_TTY=$(tty) |
| ---- |
| |
| Tag the plugins: |
| |
| ---- |
| git submodule foreach '[ "$path" == "modules/jgit" ] || git tag -s -m "v$version" "v$version"' |
| ---- |
| |
| [[build-gerrit]] |
| === Build Gerrit |
| |
| * 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-gerrit]] |
| === Publish the Gerrit Release |
| |
| [[publish-to-maven-central]] |
| ==== Publish the Gerrit artifacts to Maven Central |
| |
| * Make sure you have done the |
| link:dev-release-deploy-config.html#deploy-configuration-setting-maven-central[ |
| configuration] for deploying to Maven Central. |
| |
| * Make sure that the version is updated in the `version.bzl` file and in |
| the `*_pom.xml` files as described in the link:#update-versions[Update |
| Versions and Create Release Tag] section. |
| |
| * Push the WAR to Maven Central: |
| + |
| ---- |
| ./tools/maven/api.sh war_deploy |
| ---- |
| |
| * Push the plugin artifacts to Maven Central: |
| + |
| ---- |
| ./tools/maven/api.sh deploy |
| ---- |
| |
| * To where the artifacts are uploaded depends on the `GERRIT_VERSION` in |
| the `version.bzl` file: |
| |
| ** SNAPSHOT versions are directly uploaded into the Sonatype snapshots |
| repository and no further action is needed: |
| + |
| https://oss.sonatype.org/content/repositories/snapshots/com/google/gerrit/ |
| |
| ** Release versions are uploaded into a staging repository in the |
| link:https://oss.sonatype.org/[Sonatype Nexus Server]. |
| |
| * Verify the staging repository |
| |
| ** Go to the link:https://oss.sonatype.org/[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 |
| link:https://docs.sonatype.org/display/Repository/Sonatype+OSS+Maven+Repository+Usage+Guide#SonatypeOSSMavenRepositoryUsageGuide-8.a.2.ReleasingaStagingRepository[ |
| Sonatype OSS Maven Repository Usage Guide]. |
| + |
| [WARNING] |
| Releasing artifacts to Maven Central cannot be undone! |
| |
| ** Find the closed staging repository in the |
| link:https://oss.sonatype.org/[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: |
| + |
| https://repo1.maven.org/maven2/com/google/gerrit/ |
| |
| * [optional]: View download statistics |
| |
| ** Sign in to the |
| link:https://oss.sonatype.org/[Sonatype Nexus Server]. |
| |
| ** Click on 'Views/Repositories' in the left navigation bar under |
| 'Central Statistics'. |
| |
| ** Select `com.google.gerrit` as `Project`. |
| |
| [[publish-to-google-storage]] |
| ==== Publish the Gerrit WAR to the Google Cloud Storage |
| |
| * Go to the link:https://console.cloud.google.com/storage/browser/gerrit-releases/?project=api-project-164060093628[ |
| 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 `Upload` button. |
| |
| [[push-stable]] |
| ==== Push the Stable Branch |
| |
| * Create the stable branch `stable-$version` in the `gerrit` project via the |
| link:https://gerrit-review.googlesource.com/admin/repos/gerrit,branches[ |
| Gerrit Web UI] or by push. |
| |
| * Push the commits done on `stable-$version` to `refs/for/stable-$version` and |
| get them merged. |
| |
| * Create a change updating the `defaultbranch` field in the `.gitreview` |
| to match the branch name created. |
| |
| [[push-tag]] |
| ==== 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 git push gerrit-review tag v$version |
| ---- |
| |
| [[upload-documentation]] |
| ==== Upload the Documentation |
| |
| * Extract the documentation files from the zip file generated from |
| `bazel build searchfree`: `bazel-bin/Documentation/searchfree.zip`. |
| |
| * Upload the files manually via web browser to the appropriate folder |
| in the |
| link:https://console.cloud.google.com/storage/browser/gerrit-documentation/?project=api-project-164060093628[ |
| gerrit-documentation] storage bucket. |
| |
| [[finalize-release-notes]] |
| === Finalize the Release Notes |
| |
| Submit any previously uploaded notes change on the homepage project. |
| |
| [[finalize-issues]] |
| ==== 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 |
| to say `Status=Released`. Make sure the pulldown says `All Issues` |
| because `Status=Submitted` is considered a closed issue. |
| |
| [[announce]] |
| ==== 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 |
| ---- |
| |
| [[increase-version]] |
| === 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.bzl` file: |
| |
| ---- |
| ./tools/version.py 2.6-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]] |
| === 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 |
| ---- |
| |
| [[update-api-version-in-bazlets-repository]] |
| |
| Bazlets is used by gerrit plugins to simplify build process. To allow the |
| new released version to be used by gerrit plugins, |
| link:https://gerrit.googlesource.com/bazlets/+/master/gerrit_api.bzl#8[gerrit_api.bzl] |
| must reference the new version. Upload a change to bazlets repository with |
| api version upgrade. |
| |
| [[clean-up-on-master]] |
| === 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 link:dev-processes.html#deprecating-features[Deprecating features] for |
| details. |
| |
| GERRIT |
| ------ |
| Part of link:index.html[Gerrit Code Review] |
| |
| SEARCHBOX |
| --------- |