Improve release documentation
Added more details to the release documentation and fixed some minor
issues.
Change-Id: Ifd5be47bee1dc0886f87dcdaa8e7826a66c4f1b4
Signed-off-by: Edwin Kempin <edwin.kempin@sap.com>
diff --git a/Documentation/dev-release-deploy-config.txt b/Documentation/dev-release-deploy-config.txt
new file mode 100644
index 0000000..bc52d50
--- /dev/null
+++ b/Documentation/dev-release-deploy-config.txt
@@ -0,0 +1,135 @@
+Deploy Gerrit Artifacts
+=======================
+
+Gerrit Artifacts are stored on
+link:https://developers.google.com/storage/[Google Cloud Storage].
+Via the link:https://code.google.com/apis/console/[API Console] the
+Gerrit maintainers have access to the `Gerrit Code Review` project.
+This projects host several buckets for storing Gerrit artifacts:
+
+* `gerrit-api`:
++
+Bucket to store the Gerrit Extension API Jar and the Gerrit Plugin API
+Jar.
+
+* `gerrit-maven`:
++
+Bucket to store Gerrit Subproject Artifacts (e.g. `gwtexpui`,
+`gwtjsonrpc` etc.).
+
+* `gerrit-plugins`:
++
+Bucket to store Gerrit Core Plugin Artifacts.
+
+[[deploy-configuration-settings-xml]]
+Deploy Configuration in Maven `settings.xml`
+--------------------------------------------
+
+To upload artifacts to a bucket the user must authenticate with a
+username and password. The username and password need to be retrieved
+from the link:https://code.google.com/apis/console/[API Console]:
+
+* Go to the `Gerrit Code Review` project
+* In the menu on the left select `Google Cloud Storage` >
+`Interoperable Access`
+* Use the `Access Key` as username
+* Click under `Secret` on the `Show` button to find the password
+
+To make the username and password known to Maven, they must be
+configured in the `~/.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-api-repository</id>
+ <username>GOOG..EXAMPLE.....EXAMPLE</username>
+ <password>EXAMPLE..EXAMPLE..EXAMPLE</password>
+ </server>
+ <server>
+ <id>gerrit-maven-repository</id>
+ <username>GOOG..EXAMPLE.....EXAMPLE</username>
+ <password>EXAMPLE..EXAMPLE..EXAMPLE</password>
+ </server>
+ <server>
+ <id>gerrit-plugins-repository</id>
+ <username>GOOG..EXAMPLE.....EXAMPLE</username>
+ <password>EXAMPLE..EXAMPLE..EXAMPLE</password>
+ </server>
+ </servers>
+ </settings>
+----
+
+[[deploy-configuration-subprojects]]
+Gerrit Subprojects
+~~~~~~~~~~~~~~~~~~
+
+* You will need to have the following in the `pom.xml` to make it
+deployable to the `gerrit-maven` storage bucket:
+
+----
+ <distributionManagement>
+ <repository>
+ <id>gerrit-maven-repository</id>
+ <name>Gerrit Maven Repository</name>
+ <url>s3://gerrit-maven@commondatastorage.googleapis.com</url>
+ <uniqueVersion>true</uniqueVersion>
+ </repository>
+ </distributionManagement>
+----
+
+
+* Add this to the `pom.xml` to enable the wagon provider:
+
+----
+ <build>
+ <extensions>
+ <extension>
+ <groupId>net.anzix.aws</groupId>
+ <artifactId>s3-maven-wagon</artifactId>
+ <version>3.2</version>
+ </extension>
+ </extensions>
+ </build>
+----
+
+
+[[deploy-configuration-core-plugins]]
+Gerrit Core Plugins
+~~~~~~~~~~~~~~~~~~~
+
+* You will need to have the following in the `pom.xml` to make it
+deployable to the `gerrit-plugins` storage bucket:
+
+----
+ <distributionManagement>
+ <repository>
+ <id>gerrit-plugins-repository</id>
+ <name>Gerrit Plugins Repository</name>
+ <url>s3://gerrit-plugins@commondatastorage.googleapis.com</url>
+ <uniqueVersion>true</uniqueVersion>
+ </repository>
+ </distributionManagement>
+----
+
+
+* Add this to the `pom.xml` to enable the wagon provider:
+
+----
+ <build>
+ <extensions>
+ <extension>
+ <groupId>net.anzix.aws</groupId>
+ <artifactId>s3-maven-wagon</artifactId>
+ <version>3.2</version>
+ </extension>
+ </extensions>
+ </build>
+----
+
+
+GERRIT
+------
+Part of link:index.html[Gerrit Code Review]
diff --git a/Documentation/dev-release-subproject.txt b/Documentation/dev-release-subproject.txt
index 799ff2d..5e3770d 100644
--- a/Documentation/dev-release-subproject.txt
+++ b/Documentation/dev-release-subproject.txt
@@ -1,96 +1,106 @@
Making a Release of a Gerrit Subproject / Core Plugin
=====================================================
-Preparing a New Snapshot for Publishing
----------------------------------------
+[[make-snapshot]]
+Make a Snapshot
+---------------
-* You will need to have the following in the `pom.xml` to make it
- deployable to the `gerrit-maven` storage bucket:
+* Only for plugins:
+** In the `pom.xml` update the Gerrit version under `properties` >
+`Gerrit-ApiVersion` to the version of the new Gerrit
+release.
+** Make sure that the URL for the Maven repository with the id
+`gerrit-api-repository` in the `pom.xml` is correct.
++
+If `Gerrit-ApiVersion` references a released Gerrit version it must be
+`https://gerrit-api.commondatastorage.googleapis.com/release/`, if
+`Gerrit-ApiVersion` references a snapshot Gerrit version it must be
+`https://gerrit-api.commondatastorage.googleapis.com/snapshot/`.
-----
- <distributionManagement>
- <repository>
- <id>gerrit-maven</id>
- <name>gerrit Maven Repository</name>
- <url>s3://gerrit-maven@commondatastorage.googleapis.com</url>
- <uniqueVersion>true</uniqueVersion>
- </repository>
- </distributionManagement>
-----
+* Build the latest snapshot and install it into the local Maven
+repository:
++
+====
+ mvn clean install
+====
+
+* Test Gerrit with this snapshot locally
-* Add this to the `pom.xml` to enable the wagon provider:
+Publish Snapshot
+----------------
-----
- <build>
- <extensions>
- <extension>
- <groupId>net.anzix.aws</groupId>
- <artifactId>s3-maven-wagon</artifactId>
- <version>3.2</version>
- </extension>
- </extensions>
- </build>
-----
+If a Snapshot for a Subproject was created that should be referenced by
+Gerrit while current Gerrit development is ongoing, this Snapshot needs
+to be published.
+* Make sure you have done the configuration needed for deployment:
+** link:dev-release-deploy-config.html#deploy-configuration-settings-xml[
+Configuration in Maven `settings.xml`]
+** link:dev-release-deploy-config.html#deploy-configuration-subprojects[
+Configuration for Subprojects in `pom.xml`]
-* Add your username and password to your `~/.m2/settings.xml` file.
- These need to come from the link:https://code.google.com/apis/console/[API Console].
-
-----
- <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</id>
- <username>GOOG..EXAMPLE.....EXAMPLE</username>
- <password>EXAMPLE..EXAMPLE..EXAMPLE</password>
- </server>
- </servers>
- </settings>
-----
-
-
-Making a Snapshot
------------------
-
-* Only for plugins: in the `pom.xml` update the Gerrit version under
-`properties` > `Gerrit-ApiVersion` to the version of the new Gerrit
-release
-* First build and deploy the latest snapshot and ensure that Gerrit
-builds/runs with this snapshot
-
-* Deploy the snapshot:
-
+* Deploy the new snapshot:
++
====
mvn deploy
====
+* Change the version in the Gerrit parent `pom.xml` for the Subproject
+to the `SNAPSHOT` version
++
+When Gerrit gets released, a release of the Subproject has to be done
+and Gerrit has to reference the released Subproject version.
-Making a Release
-----------------
-* First deploy (and test) the latest snapshot for the subproject/plugin
+[[prepare-release]]
+Prepare the Release
+-------------------
+
+* link:#make-snapshot[First create (and test) the latest snapshot for
+the subproject/plugin]
* Update the top level `pom.xml` in the subproject/plugin 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)
-
+* Create the Release Tag
++
====
git tag -a -m "prolog-cafe 1.3" v1.3
- git push gerrit-review refs/tags/v1.3:refs/tags/v1.3
====
+* Build and install into local Maven repository:
++
+====
+ mvn clean install
+====
+
+
+[[publish-release]]
+Publish the Release
+-------------------
+
+* Make sure you have done the configuration needed for deployment:
+** link:dev-release-deploy-config.html#deploy-configuration-settings-xml[
+Configuration in Maven `settings.xml`]
+** Configuration in `pom.xml` for
+link:dev-release-deploy-config.html#deploy-configuration-subprojects[Subprojects] or
+link:dev-release-deploy-config.html#deploy-configuration-core-plugins[Core Plugins]
+
* Deploy the new release:
-
++
====
- mvn deploy
+ mvn deploy
+====
+
+* Push the pom change(s) to the project's repository
+`refs/for/<master|stable>`
+
+* Push the Release Tag
++
+====
+ git push gerrit-review refs/tags/v1.3:refs/tags/v1.3
====
diff --git a/Documentation/dev-release.txt b/Documentation/dev-release.txt
index 5ea3042..7a963fc 100644
--- a/Documentation/dev-release.txt
+++ b/Documentation/dev-release.txt
@@ -11,7 +11,7 @@
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
+hopefully serve as both a how to for those new to the process
and as a checklist for those already familiar with these
tasks.
@@ -20,106 +20,181 @@
-------------------
Here are some guidelines on release approaches depending on the
-type of release you want to make (stable-fix, stable, RC0, RC1...).
+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.
+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
+* Create a Gerrit `RC0`
-* If needed create a Gerrit RC1
+* If needed create a Gerrit `RC1`
[NOTE]
========================================================================
You may let in a few features to this release
========================================================================
-* If needed create a Gerrit RC2
+* 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)
+* Finally create the `stable` release (no `RC`)
Stable-Fix
~~~~~~~~~~
-Stable-fix releases should likely only contain bug fixes and doc updates.
+`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
-
+* This type of release does not need any RCs, release when the
+objectives are met
Create the Actual Release
---------------------------
-In the example commands below we assume that the last release was '2.4' and that
-we are preparing '2.5' release.
+To create a Gerrit release the following steps have to be done:
-Prepare the Subprojects
-~~~~~~~~~~~~~~~~~~~~~~~
-
-* Publish the latest snapshot for all subprojects
-* Freeze all subprojects and link:dev-release-subproject.html[publish]
- them!
+. 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
~~~~~~~~~~~~~~
-* Create a `stable-2.5` branch for making the new release
+In all example commands it is assumed that the last release was `2.4`
+and that now the `2.5` release is prepared.
-* In the `master` branch: Update the poms for the Gerrit version, push for
-review, get merged
-====
- tools/version.sh --snapshot=2.5
-====
+[[prepare-war-and-plugin-api]]
+Prepare the Gerrit WAR and the Plugin API Jar
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-* Checkout the `stable-2.5` branch
-* Update the top level `pom.xml` in Gerrit to ensure that none of the
-Subprojects point to snapshot releases
+* Create locally a `stable-2.5` branch for making the new release
-* Tag
+* 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 (without plugins)
-
+* 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.
+========================================================================
-[[plugin-api]]
-Publish the Plugin API JAR File
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+* Sanity check WAR
-* Push JAR to `commondatastorage.googleapis.com`
-** Run `tools/deploy_api.sh`
-Prepare the Core Plugins
-~~~~~~~~~~~~~~~~~~~~~~~~
-* link:dev-release-subproject.html[Release and publish] the core plugins
+[[prepare-core-plugins]]
+Prepare Core Plugins
+^^^^^^^^^^^^^^^^^^^^
+The core plugins to be prepared are:
-Package Gerrit with Plugins
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-* Ensure that the core plugins listed in `gerrit-package-plugins/pom.xml`
-point to the latest release version (no dependency to snapshot versions)
+* `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
@@ -127,35 +202,91 @@
* Find WAR that includes the core plugins at
`gerrit-package-plugins\target\gerrit-full-v2.5.war`
-* Sanity check WAR
-Publish to the Project Locations
---------------------------------
+* 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`.
-WAR File
-~~~~~~~~
+* Test the new Gerrit version
-* Upload WAR to code.google.com/p/gerrit (manual web browser)
+[[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
+** Use the `New Download` button
* Update labels:
-** new war: [release-candidate], featured...
-** old war: deprecated
+** new war: [`release-candidate`], `featured`...
+** old war: `deprecated`
-Tag
-~~~
-* Push the New Tag
+[[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
====
-Docs
-~~~~
+[[upload-documentation]]
+Upload the Documentation
+^^^^^^^^^^^^^^^^^^^^^^^^
====
make -C Documentation PRIOR=2.4 update
@@ -167,14 +298,14 @@
* 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
+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.
+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:
@@ -188,30 +319,33 @@
========================================================================
-Issues
-~~~~~~
+[[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.2.2 is released?
+ 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.2.2 once the change is submitted, but before the
+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.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.
+``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.
-Mailing List
-~~~~~~~~~~~~
+[[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:
+* 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)
@@ -241,7 +375,7 @@
-Martin
----
-* Add an entry to the NEWS section of the main Gerrit project web page
+* 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:
----
@@ -252,18 +386,33 @@
** Go to: http://groups.google.com/group/repo-discuss/topics
** Click on the announcement thread
** Near the top right, click on options
-** Under options, cick the "Display this top first" checkbox
+** 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)
-Merging Stable Fixes to master
-------------------------------
+[[increase-version]]
+Increase Gerrit Version for Current Development
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-After every stable-fix release, stable should be merged to master to
-ensure that none of the fixes ever get lost.
+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
