Documentation/dev-release.txt - gerrit - Git at Google

 = 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.


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


 [[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-setting-maven-central[
 configuration needed for deployment]

 * Push the Jars to the Maven Central:
 +
 ----
   buck build api_deploy
 ----

 * Troubleshooting: to see the commands that are execured in Buck build process
 environment variable VERBOSE can be set:
 +
 ----
   VERBOSE=1 buck build api_deploy
 ----

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

 * Push the WAR to the Maven Central:
 +
 ----
   buck build war_deploy
 ----


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

 Build the release notes:

 ----
   make -C ReleaseNotes
 ----

 * Upload html files to the storage bucket via `https://cloud.google.com/console` (manual via web browser)
 ** Documentation html files must be extracted from `buck-out/gen/Documentation/html.zip`
 * 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)

 ----
 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 the
 `VERSION` file, and plugin archetypes' `pom.xml` files. Push the change
 for review and get it merged.


 [[publish-plugins-archetypes-to-maven-central]]
 === Publish plugin archetypes to Maven Central

 Make sure you have done the
 link:dev-release-deploy-config.html#deploy-configuration-setting-maven-central[
 configuration needed for deployment]

 ----
   ./tools/plugin_archetype_deploy.sh
 ----

 [[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
 ---------
	= 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.


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


	[[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-setting-maven-central[
	configuration needed for deployment]

	* Push the Jars to the Maven Central:
	+
	----
	buck build api_deploy
	----

	* Troubleshooting: to see the commands that are execured in Buck build process
	environment variable VERBOSE can be set:
	+
	----
	VERBOSE=1 buck build api_deploy
	----

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

	* Push the WAR to the Maven Central:
	+
	----
	buck build war_deploy
	----


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

	Build the release notes:

	----
	make -C ReleaseNotes
	----

	* Upload html files to the storage bucket via `https://cloud.google.com/console` (manual via web browser)
	** Documentation html files must be extracted from `buck-out/gen/Documentation/html.zip`
	* 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)

	----
	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 the
	`VERSION` file, and plugin archetypes' `pom.xml` files. Push the change
	for review and get it merged.


	[[publish-plugins-archetypes-to-maven-central]]
	=== Publish plugin archetypes to Maven Central

	Make sure you have done the
	link:dev-release-deploy-config.html#deploy-configuration-setting-maven-central[
	configuration needed for deployment]

	----
	./tools/plugin_archetype_deploy.sh
	----

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