Add a release preparation document
Document what it takes to make a Gerrit stable
or stable-fix release, and how to release Gerrit
subprojects.
Change-Id: I462b83d3f4081997481ce5dc4680b0662a6aa977
diff --git a/Documentation/dev-release-subproject.txt b/Documentation/dev-release-subproject.txt
new file mode 100644
index 0000000..a9d0553
--- /dev/null
+++ b/Documentation/dev-release-subproject.txt
@@ -0,0 +1,95 @@
+Making a Gerrit Sub Project Release
+===================================
+
+Preparing a New Gerrit Subproject Snapshot for Publishing
+---------------------------------------------------------
+
+* You will need to have the following in the pom.xml to make it deployable to:
+gerrit-maven-repository.googlecode.com
+----
+ <distributionManagement>
+ <snapshotRepository>
+ <id>gerrit-snapshot-repository</id>
+ <name>gerrit Snapshot Repository</name>
+ <url>dav:https://gerrit-maven-repository.googlecode.com/svn/</url>
+ <uniqueVersion>true</uniqueVersion>
+ </snapshotRepository>
+
+ <repository>
+ <id>gerrit-maven-repository</id>
+ <name>gerrit Maven Repository</name>
+ <url>dav:https://gerrit-maven-repository.googlecode.com/svn/</url>
+ <uniqueVersion>true</uniqueVersion>
+ </repository>
+ </distributionManagement>
+----
+
+
+* Since ubuntu maven is incomplete, also add this to the pom.xml:
+
+----
+ <build>
+ <extensions>
+ <extension>
+ <groupId>org.apache.maven.wagon</groupId>
+ <artifactId>wagon-webdav-jackrabbit</artifactId>
+ <version>1.0-beta-6</version>
+ </extension>
+ </extensions>
+ </build>
+----
+
+
+* Add your username and password to your ~/.m2/settings.xml file:
+
+----
+ <settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
+ <servers>
+ <server>
+ <id>gerrit-maven-repository</id>
+ <username>JohnDoe@example.com</username>
+ <password>OpenSessame</password>
+ </server>
+
+ <server>
+ <id>gerrit-snapshot-repository</id>
+ <username>JohnDoe@example.com</username>
+ <password>OpenSessame</password>
+ </server>
+ </servers>
+ </settings>
+----
+
+
+Making a Gerrit Subproject Snapshot
+-----------------------------------
+
+* First build and deploy the latest snapshot and ensure that Gerrit builds
+with this snapshot
+
+* Deploy the snapshot:
+
+----
+ mvn deploy
+----
+
+
+Making a Gerrit Subproject Release
+----------------------------------
+
+* First deploy (and test) the latest snapshot for this subprojects
+
+* Update the top level pom.xml in the subproject to reflect the new project
+version (the exact value of the tag you will create below)
+
+* Commit the pom change and push to the project's repo refs/for/<master/stable>
+
+* Tag the version you just pushed (and push the tag)
+
+* Deploy the new release:
+
+----
+ mvn deploy
+----
diff --git a/Documentation/dev-release.txt b/Documentation/dev-release.txt
new file mode 100644
index 0000000..f439504
--- /dev/null
+++ b/Documentation/dev-release.txt
@@ -0,0 +1,222 @@
+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
+hopefuly 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
+~~~~~~
+
+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
+
+
+
+Create the Actual Release
+---------------------------
+
+Prepare the Subprojects
+~~~~~~~~~~~~~~~~~~~~~~~
+
+* Publish the latest snapshot for all subprojects
+* Freeze all subprojects and link:dev-release-subproject.html[publish]
+ them!
+
+
+Prepare Gerrit
+~~~~~~~~~~~~~~
+
+* Update the top level pom in Gerrit to ensure that none of the Subprojects
+ point to snapshot releases
+
+* Update the poms for the Gerrit version, push for review, get merged
+
+====
+ tools/version.sh --snapshot=2.3
+====
+
+* Tag
+
+====
+ git tag -a -m "gerrit 2.2.2-rc0" v2.2.2-rc0
+ git tag -a -m "gerrit 2.2.2.1" v2.2.2.1
+====
+
+* Build
+
+====
+ ./tools/release.sh
+====
+
+* Sanity check WAR
+
+
+Publish to the Project Locations
+--------------------------------
+
+WAR File
+~~~~~~~~
+
+* Upload WAR to code.google.com/p/gerrit (manual 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
+
+Tag
+~~~
+
+* Push the New Tag
+
+====
+ git push google refs/tags/v2.2.2.1:refs/tags/v2.2.2.1
+====
+
+
+Docs
+~~~~
+
+====
+ make -C Documentation PRIOR=2.2.2 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
+** 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
+
+(requires overriding svn username on command line)
+========================================================================
+
+
+Issues
+~~~~~~
+
+====
+ How do the issues get updated? Do you run a script to do
+ this? When do you do it, after the final 2.2.2 is released?
+====
+
+By hand.
+
+Our current process is an issue should be updated to say Status =
+Submitted, FixedIn-2.2.2 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.2.2'' 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.
+
+
+Mailing List
+~~~~~~~~~~~~
+
+* Send an email to the mailing list to annouce 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
+----
+
+
+Merging Stable Fixes to master
+------------------------------
+
+After every stable-fix release, stable should be merged to master to
+ensure that none of the 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
+====
diff --git a/Documentation/index.txt b/Documentation/index.txt
index 5143bf7..a926778 100644
--- a/Documentation/index.txt
+++ b/Documentation/index.txt
@@ -49,6 +49,8 @@
* link:dev-contributing.html[Contributing to Gerrit]
* link:dev-design.html[System Design]
* link:i18n-readme.html[i18n Support]
+* link:dev-release.html[Developer Release]
+* link:dev-release-subproject.html[Developer Subproject Release]
Resources
---------
