gerrit/Documentation/dev-release.txt

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:#prepare-gerrit[Prepare the Gerrit Release]
.. link:#prepare-war-and-plugin-api[Prepare the Gerrit WAR and the Plugin API Jar]
.. link:#prepare-core-plugins[Prepare the Core Plugins]
.. link:#prepare-war-with-plugins[Prepare Gerrit WAR with Core Plugins]
. link:#publish-gerrit[Publish the Gerrit Release]
.. link:#extension-and-plugin-api[Publish the Extension and Plugin API Jars]
.. link:#publish-core-plugins[Publish the Core Plugins]
.. 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:

* `gwtexpui`
* `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 version of the Subproject in the Gerrit parent `pom.xml`
to the released version


[[prepare-gerrit]]
Prepare Gerrit
~~~~~~~~~~~~~~

In all example commands it is assumed that the last release was `2.4`
and that now the `2.5` release is prepared.


[[prepare-war-and-plugin-api]]
Prepare the Gerrit WAR and the Plugin API Jar
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

* link:dev-readme.html#run-acceptance-tests[Run the acceptance tests]

* Create locally a `stable-2.5` branch for making the new release

* Check in the Gerrit parent `pom.xml` that no `SNAPSHOT` version of a
Subproject is referenced
+
If there is a dependency to a `SNAPSHOT` version,
link:#subproject[release the subproject] first.

* Create a tag for the Gerrit release
+
For an `RC` release:
+
====
 git tag -a -m "gerrit 2.5-rc0" v2.5-rc0
====
+
For a final `stable` release:
+
====
 git tag -a -m "gerrit 2.5" v2.5
====

* Build the Gerrit WAR (without plugins) and the Plugin API Jar
+
====
 ./tools/release.sh
====
+
[WARNING]
========================================================================
Make sure you are compiling the release for all browsers. Check in your
Maven `~/.m2/settings.xml` file that no Maven profile is active that
limits the compilation to a certain browser.
========================================================================

* Sanity check WAR


[[prepare-core-plugins]]
Prepare Core Plugins
^^^^^^^^^^^^^^^^^^^^
The core plugins to be prepared are:

* `plugins/replication`

For each core plugin do:

* link:dev-release-subproject.html#make-snapshot[Make a snapshot and test it]
* link:dev-release-subproject.html#prepare-release[Prepare the Release]

* Update the version of the Core Plugin in
`gerrit-package-plugins/pom.xml` to the released version

[WARNING]
========================================================================
Updating the plugin versions in `gerrit-package-plugins/pom.xml`
invalidates the Gerrit Release Tag which was created before.

If needed delete the tag and recreate it!
========================================================================


[[prepare-war-with-plugins]]
Prepare Gerrit WAR with Core Plugins
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

* Ensure that the Core Plugins listed in `gerrit-package-plugins/pom.xml`
point to the latest release version (no dependency to `SNAPSHOT` versions)

* Ensure that the release tag points to the `HEAD` commit

* Include core plugins into WAR
+
====
 $ ./tools/version.sh --release && mvn clean package -f gerrit-package-plugins/pom.xml
 $ ./tools/version.sh --reset
====

* Find WAR that includes the core plugins at
`gerrit-package-plugins\target\gerrit-full-v2.5.war`

* Compare `gerrit-package-plugins\target\gerrit-full-v2.5.war` with
  `gerrit-war\target\gerrit-v2.5.war`
+
The only difference should be the core plugins jars under
`WEB-INF\plugins`.

* Test the new Gerrit version

[[publish-gerrit]]
Publish the Gerrit Release
~~~~~~~~~~~~~~~~~~~~~~~~~~


[[extension-and-plugin-api]]
Publish the Extension and Plugin API Jars
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

* Make sure you have done the
link:dev-release-deploy-config.html#deploy-configuration-settings-xml[
configuration needed for deployment]

* Push the Jars to `commondatastorage.googleapis.com`:
+
----
  ./tools/deploy_api.sh
----


[[publish-core-plugins]]
Publish the Core Plugins
^^^^^^^^^^^^^^^^^^^^^^^^

* link:dev-release-subproject.html#publish-release[Publish the Release]


[[publish-gerrit-war]]
Publish the Gerrit WAR (with Core Plugins)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

* The WAR file to upload is `gerrit-package-plugins\target\gerrit-full-v2.5.war`
* Upload WAR to `code.google.com/p/gerrit` (manual via web browser)
** Go to http://code.google.com/p/gerrit/downloads/list
** Use the `New Download` button

* Update labels:
** new war: [`release-candidate`], `featured`...
** old war: `deprecated`


[[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 WebUI] 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
+
For an `RC`:
+
====
 git push gerrit-review refs/tags/v2.5-rc0:refs/tags/v2.5-rc0
====
+
For a final `stable` release:
+
====
 git push gerrit-review refs/tags/v2.5:refs/tags/v2.5
====


[[upload-documentation]]
Upload the Documentation
^^^^^^^^^^^^^^^^^^^^^^^^

====
 make -C Documentation PRIOR=2.4 update
 make -C ReleaseNotes update
====

(no +PRIOR=+... if updating the same release again during RCs)

* Update Google Code project links
** Go to http://code.google.com/p/gerrit/admin
** Point the main page to the new docs. The link to the documentation has to be
updated at two places: in the project description and also in the `Links`
section.
** Point the main page to the new release notes

[NOTE]
========================================================================
The docs makefile does an `svn cp` of the prior revision of the docs to
branch the docs so you have less to upload on the new docs.

User and password from here:

    https://code.google.com/hosting/settings

If subversion assumes a different username than your google one and asks for a
password right away simply hit enter. Subversion will fail and then ask for
another username and password. This time enter the username and password from
the page linked above. After that subversion should save the username/password
somewhere under `~/.subversion/auth` folder.
========================================================================


[[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)

----
To: Repo and Gerrit Discussion <repo-discuss@googlegroups.com>
Subject: Announce: Gerrit 2.2.2.1  (Stable bug fix update)

I am pleased to announce Gerrit Code Review 2.2.2.1.

Download:

  http://code.google.com/p/gerrit/downloads/list


This release is a stable bug fix release with some
documentation updates including a new "Contributing to
Gerrit" doc:

  http://gerrit-documentation.googlecode.com/svn/Documentation/2.2.2/dev-contributing.html


To read more about the bug fixes:

  http://gerrit-documentation.googlecode.com/svn/ReleaseNotes/ReleaseNotes-2.2.2.1.html

-Martin
----

* 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 options
** Under options, click the "Display this top first" checkbox
** and Save

* 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. Update the Gerrit version in each
`pom.xml` file to the next `SNAPSHOT`version. Push the change for
review and get it merged.

====
 tools/version.sh --snapshot=2.6
====


[[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]