| = 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 |
| |
| * 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]] |
| === 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: |
| |
| . link:#subproject[Release Subprojects] |
| . link:#build-gerrit[Build the Gerrit Release] |
| . link:#publish-gerrit[Publish the Gerrit Release] |
| .. link:#extension-and-plugin-api[Publish the Extension and Plugin API Jars] |
| .. link:#publish-gerrit-war[Publish the Gerrit WAR (with Core Plugins)] |
| .. link:#push-stable[Push the Stable Branch] |
| .. link:#push-tag[Push the Release Tag] |
| .. link:#upload-documentation[Upload the Documentation] |
| .. link:#update-issues[Update the Issues] |
| .. link:#announce[Announce on Mailing List] |
| . link:#increase-version[Increase Gerrit Version for Current Development] |
| . link:#merge-stable[Merge `stable` into `master`] |
| |
| |
| [[subproject]] |
| === 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. |
| |
| * link:dev-release-subproject.html#make-snapshot[Make a snapshot and test it] |
| * link:dev-release-subproject.html#prepare-release[Prepare the Release] |
| * link:dev-release-subproject.html#publish-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]] |
| === 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 Gerrit |
| |
| * Build the Gerrit WAR and API JARs |
| + |
| ---- |
| buck build release |
| buck build api_install |
| ---- |
| |
| * Sanity check WAR |
| * Test the new Gerrit version |
| |
| [[publish-gerrit]] |
| === Publish the Gerrit Release |
| |
| [[publish-gerrit-war]] |
| ==== Publish the Gerrit WAR (with Core Plugins) |
| |
| * Upload the WAR to the Google Cloud Storage |
| |
| ** go to https://console.developers.google.com/project/164060093628/storage/gerrit-releases/ |
| ** make sure you are signed in with your Gmail account |
| ** manually upload the Gerrit WAR file by using the `Upload` button |
| |
| [[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` 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: |
| + |
| ---- |
| 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: |
| |
| ** 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 |
| + |
| How to do this is described in the |
| link:https://docs.sonatype.org/display/Repository/Sonatype+OSS+Maven+Repository+Usage+Guide#SonatypeOSSMavenRepositoryUsageGuide-8.a.1.ClosingaStagingRepository[ |
| Sonatype OSS Maven Repository Usage Guide]. |
| |
| ** 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: |
| + |
| http://central.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`. |
| |
| |
| [[push-stable]] |
| ==== Push the Stable Branch |
| |
| * Create the stable branch `stable-2.5` in the `gerrit` project via the |
| link:https://gerrit-review.googlesource.com/#/admin/projects/gerrit,branches[ |
| 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-tag]] |
| ==== 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-documentation]] |
| ==== 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 |
| link:https://console.developers.google.com/project/164060093628/storage/gerrit-documentation/[ |
| gerrit-documentation] storage bucket. The `gerrit-documentation` |
| storage bucket is accessible via the |
| link:https://cloud.google.com/console[Google Developers Console]. |
| |
| [[update-links]] |
| ==== Update Google Code project links |
| |
| * Go to http://code.google.com/p/gerrit/admin |
| * Update the documentation link in the `Resources` section of the |
| Description text, and in the `Links` section. |
| * Add a link to the new release notes in the `News` section of the |
| Description text |
| |
| [[update-issues]] |
| ==== 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]] |
| ==== 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 |
| ** Go to: http://code.google.com/p/gerrit/admin |
| ** Add entry like: |
| ---- |
| * 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 |
| ** Go to: http://groups.google.com/group/repo-discuss/topics |
| ** Click on the announcement thread |
| ** Near the top right, click on actions |
| ** Under actions, click the "Display this top first" checkbox |
| |
| * Update the previous discussion group announcement to no longer be sticky |
| ** See above (unclick checkbox) |
| |
| |
| [[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` 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]] |
| === 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 |
| ---- |
| |
| |
| GERRIT |
| ------ |
| Part of link:index.html[Gerrit Code Review] |
| |
| SEARCHBOX |
| --------- |