a1ab3e7373
Add commands for creating and pushing tags on the plugins. Also remove the distinction between pushing final release and RC release tags. This distinction is not made in the section about creating the tags. Change-Id: I4dcdc6ac81b2838b4fa9153efcecff87f3b07e3c
452 lines
13 KiB
Plaintext
452 lines
13 KiB
Plaintext
= 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
|
|
---------
|