From 00634add3e54e7c188d1b56b76e9c1898fa502a4 Mon Sep 17 00:00:00 2001
From: Markus Zoeller <mzoeller@de.ibm.com>
Date: Mon, 20 Feb 2017 16:14:03 +0100
Subject: [PATCH] docs: add release tagging and stable branch creation
 description

This change adds a how-to description of:
* how to tag a release (candidate)
* how to create a stable branch

Change-Id: Ia7fee9db91523288779b7ec200ff2ecd9c7c46e1
---
 doc/source/devref.rst | 88 ++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 86 insertions(+), 2 deletions(-)

diff --git a/doc/source/devref.rst b/doc/source/devref.rst
index f65da9b..30a87ce 100644
--- a/doc/source/devref.rst
+++ b/doc/source/devref.rst
@@ -84,13 +84,71 @@ When creating a new full release, the usual order of action is:
 
 * start during the RC phase (usually ~3 weeks before the release)
 * merge the open changes which need to make the release into master
-* create a ``stable/<release>`` branch from master (master is now open
+* tag the last commit in ``master`` with the *release candidate* tag
+* create a ``stable/<release>`` branch from that tag (master is now open
   for changes for the next release)
-* tag the last commit in that stable branch with the *release candidate* tag
 * double-check if that release candidate needs fixes
 * tag the final release candidate 1 week before the actual release
 * tag the final full release
 
+.. note:: As a project which is not under the Openstack governance, we
+   don't use the ``openstack/releases`` repository to create releases and
+   stable branches. See `New stable branch`_ for the HOW-TO.
+
+
+Tag releases
+------------
+
+Releases are done via *Git tags*. The list of releases can be found at
+https://github.com/openstack/nova-dpm/releases . To tag the first release
+candidate (RC) for the next release, follow the steps below. We use the
+*Ocata* release as an example:
+
+#. You need a key to sign the tag::
+
+   $ gpg --list-keys
+
+#. If this is not yet done, create one::
+
+   $ gpg --gen-key
+
+#. Go to the commit you want to tag (usually the latest one in ``master``)::
+
+   $ git checkout master
+   $ git pull
+
+#. (Optional) Double-check the list of current tags::
+
+   $ git tag -l
+
+#. Create a signed tag::
+
+   $ git tag -s 1.0.0.0rc1 -m "RC1 for the Ocata release"
+
+#. Push that tag via the *gerrit* remote (no Gerrit change will be created)::
+
+   $ git push gerrit 1.0.0.0rc1
+
+#. (Optional) Wait for ~5m, then you can check if the automatic release
+   process was executed::
+
+   $ git os-job 1.0.0.0rc1
+
+At this point we are done with the release of a version. You might want to
+check if the artifacts show the new version number:
+
+* The read-only github repo: https://github.com/openstack/nova-dpm/releases
+* The package on PyPi: https://pypi.python.org/pypi/nova-dpm
+* The docs on RTD: http://nova-dpm.readthedocs.io/en/latest/
+
+.. note:: RTD uses ``pbr`` to determine the version number and shows
+   a version number higher than that you pushed before, that's fine and
+   nothing to worry about.
+
+.. warning:: Further release candidates and the final release must be
+   tagged in the ``stable/<release>`` branch and **not** in the ``master``
+   branch.
+
 
 Stable Branches
 ===============
@@ -139,3 +197,29 @@ The short version of the technical side of creating a backport::
    $ git cherry-pick -x $master_commit_id
    $ git review stable/ocate
 
+New stable branch
+-----------------
+
+After the first release candidate is tagged in ``master``, you should create
+the stable branch in *Gerrit* based on that:
+
+#. Check if you are a member of the Gerrit group ``nova-dpm-release``:
+   https://review.openstack.org/#/admin/groups/1633,members
+#. This release group is allowed to create references and tags:
+   https://review.openstack.org/#/admin/projects/openstack/nova-dpm,access
+#. Go to https://review.openstack.org/#/admin/projects/openstack/nova-dpm,branches
+   and enter the branch name ``stable/<release>`` and the initial revision
+   it is based on (the release candidate tag).
+
+   #. Example for Ocata::
+
+         Branch Name: stable/ocata
+         Initial Revision: 1.0.0.0rc1
+
+   #. Example for Pike::
+
+         Branch Name: stable/pike
+         Initial Revision: 2.0.0.0rc1
+
+After this is done, every open change in Gerrit which uses ``master`` as
+target branch will be (if it will merge) part of the next release.