Update branch cutting documentation

- Update the doc for RE to either follow manual steps or use jobs
  for branch cutting jobs.
- Re-order some of the steps to minimize the time the branches are
  locked.
- Add the version bump and branch cut jobs.

Change-Id: I5e630a8160e5c46a1b4f40bc7dc189e45de1da70
Signed-off-by: Anil Belur <abelur@linuxfoundation.org>

diff --git a/docs/release-process/branch-cutting.rst b/docs/release-process/branch-cutting.rst
index eb2cd5b62714e9f0e6d5cfa6f8be01342fe9e9a1..be0457948a17bd6c8611c6d8fc44bcf5832395c1 100644 (file)
--- a/docs/release-process/branch-cutting.rst
+++ b/docs/release-process/branch-cutting.rst
@@ -9,23 +9,23 @@ permissions in order to perform the necessary task in Parentheses.
 M5 Offset 2
 ===========
 
-JJB
----
+JJB (releng/builder)
+--------------------
 
-- Export ${NEXT_RELEASE} and ${CURR_RELEASE} with new and current release names.
-  **(releng/builder committers)**
+#. Export ${NEXT_RELEASE} and ${CURR_RELEASE} with new and current release names.
+   **(releng/builder committers)**
 
-  .. code-block:: bash
+   .. code-block:: bash
 
-     export NEXT_RELEASE="Nitrogen"
-     export CURR_RELEASE="Carbon"
+      export NEXT_RELEASE="Nitrogen"
+      export CURR_RELEASE="Carbon"
 
-- Change JJB yaml files from `stream:carbon` branch pointer from `master -> stable/${CURR_RELEASE,,}`
-  and create new `stream: ${NEXT_RELEASE,,}` branch pointer to branch master. This
-  requires handling two different file formats interspersed with in autorelease projects.
-  **(releng/builder committers)**
+#. Change JJB yaml files from `stream:carbon` branch pointer from `master -> stable/${CURR_RELEASE,,}`
+   and create new `stream: ${NEXT_RELEASE,,}` branch pointer to branch master. This
+   requires handling two different file formats interspersed with in autorelease projects.
+   **(releng/builder committers)**
 
-  .. code-block:: yaml
+   .. code-block:: yaml
 
       stream:
         - Nitrogen:
@@ -33,7 +33,7 @@ JJB
         - Carbon:
             branch: stable/carbon
 
-  .. code-block:: yaml
+   .. code-block:: yaml
 
       - project:
           name: aaa-carbon
@@ -42,95 +42,134 @@ JJB
           stream: nitrogen
           branch: master
 
-  - The above manual process of updating individual files is automated with the script.
-    **(releng/builder committers)**
+   - The above manual process of updating individual files is automated with the script.
+     **(releng/builder committers)**
 
-  .. code-block:: bash
+     .. code-block:: bash
 
-      cd builder/scripts/branch_cut
-      ./branch_cutter.sh -n $NEXT_RELEASE -c $CURR_RELEASE
+        cd builder/scripts/branch_cut
+        ./branch_cutter.sh -n $NEXT_RELEASE -c $CURR_RELEASE
 
-- Review and submit the changes to releng/builder project. **(releng/builder committers)**
+#. Review and submit the changes to releng/builder project. **(releng/builder committers)**
 
 Autorelease
 -----------
 
-- Block submit permissions for registered users and elevate RE's committer rights on gerrit.
-  **(Helpdesk)**
+#. Block submit permissions for registered users and elevate RE's committer rights on gerrit.
+   **(Helpdesk)**
 
-  .. figure:: images/gerrit-update-committer-rights.png
+   .. figure:: images/gerrit-update-committer-rights.png
 
-  .. note::
+   .. note::
 
-     Enable **Exclusive** checkbox for the submit button to override any existing persmissions.
+      Enable **Exclusive** checkbox for the submit button to override any existing permissions.
 
-- Setup releng/autorelease repository.
-  **(Release Engineering Team)**
+#. Enable create reference permissions on gerrit for RE's to submit .gitreview patches.
+   **(Helpdesk)**
 
-  .. code-block:: bash
+   .. figure:: images/gerrit-update-create-reference.png
 
-      git review -s
-      git submodule foreach 'git review -s'
-      git checkout master
-      git submodule foreach 'git checkout master'
-      git pull --rebase
-      git submodule foreach 'git pull --rebase'
+   .. note::
 
-- Create stable/${CURR_RELEASE} branches based on HEAD master.
-  **(Release Engineering Team)**
+      Enable Exclusive checkbox override any existing permissions.
 
-  .. code-block:: bash
+#.  Start the branch cut job or use the manual steps below for branch cutting autorelease. **(Release Engineering Team)**
+#. Start the version bump job or use the manual steps below for version bump autorelease. **(Release Engineering Team)**
+#. Merge all .gitreview patches submitted though the job or manually. **(Release Engineering Team)**
+#. Remove create reference permissions set on gerrit for RE's. **(Helpdesk)**
+#. Merge all version bump patches in the order of dependencies. **(Release Engineering Team)**
+#. Re-enable submit permissions for registered users and disable elevated RE committer rights on gerrit. **(Helpdesk)**
+#. Notify release list on branch cutting work completion. **(Release Engineering Team)**
 
-      git submodule foreach 'git checkout -b stable/${CURR_RELEASE,,} origin/master'
-      git push gerrit stable/${CURR_RELEASE,,}
-      git submodule foreach 'git push gerrit stable/${CURR_RELEASE,,}'
 
-- Enable create reference permissions on gerrit for RE's to submit .gitreview patches.
-  **(Helpdesk)**
+Branch cut job (Autorelease)
+----------------------------
+Branch cutting can be performed either through the job or manually.
 
-  .. figure:: images/gerrit-update-create-reference.png
+#. Start the autorelease-branch-cut job
+   **(Release Engineering Team)**
 
-  .. note::
+Manual steps to branch cut (Autorelease)
+----------------------------------------
 
-     Enable Exclusive checkbox override any existing persmissions.
+#. Setup releng/autorelease repository.
+   **(Release Engineering Team)**
 
-- Contribute .gitreview updates to stable/${CURR_RELEASE,,}.
-  **(Release Engineering Team)**
+   .. code-block:: bash
 
-  .. code-block:: bash
+       git review -s
+       git submodule foreach 'git review -s'
+       git checkout master
+       git submodule foreach 'git checkout master'
+       git pull --rebase
+       git submodule foreach 'git pull --rebase'
 
-      git submodule foreach sed -i -e "s#defaultbranch=master#defaultbranch=stable/${CURR_RELEASE,,}#" .gitreview
-      git submodule foreach git commit -asm "Update .gitreview to stable/${CURR_RELEASE,,}"
-      git submodule foreach 'git review -t ${CURR_RELEASE,,}-branch-cut'
-      sed -i -e "s#defaultbranch=master#defaultbranch=stable/${CURR_RELEASE,,}#" .gitreview
-      git add .gitreview
-      git commit -s -v -m "Update .gitreview to stable/${CURR_RELEASE,,}"
-      git review -t  ${CURR_RELEASE,,}-branch-cut
+#. Enable create reference permissions on gerrit for RE's to submit .gitreview patches.
+   **(Helpdesk)**
 
-- Merge all .gitreview patches submitted in the above step. **(Release Engineering Team)**
-- Remove create reference permissions set on gerrit for RE's. **(Helpdesk)**
-- Version bump master by x.(y+1).z. **(Release Engineering Team)**
+   .. figure:: images/gerrit-update-create-reference.png
 
-  .. code-block:: bash
+   .. note::
 
-      git checkout master
-      git submodule foreach 'git checkout master'
-      pip install lftools
-      lftools version bump ${CURR_RELEASE}
+      Enable Exclusive check-box override any existing permissions.
 
-- Exclude version bump changes to release notes. **(Release Engineering Team)**
+#. Create stable/${CURR_RELEASE} branches based on HEAD master.
+   **(Release Engineering Team)**
 
-  .. code-block:: bash
+   .. code-block:: bash
 
-      git checkout pom.xml scripts/
+       git checkout -b stable/${CURR_RELEASE,,} origin/master
+       git submodule foreach 'git checkout -b stable/${CURR_RELEASE,,} origin/master'
+       git push gerrit stable/${CURR_RELEASE,,}
+       git submodule foreach 'git push gerrit stable/${CURR_RELEASE,,}'
 
-- Push version bump master changes to gerrit. **(Release Engineering Team)**
+#. Contribute .gitreview updates to stable/${CURR_RELEASE,,}.
+   **(Release Engineering Team)**
 
-  .. code-block:: bash
+   .. code-block:: bash
 
-      git submodule foreach 'git commit -asm "Bump versions by x.(y+1).z for next dev cycle"'
-      git submodule foreach 'git review -t nitrogen-br-cut'
+       git submodule foreach sed -i -e "s#defaultbranch=master#defaultbranch=stable/${CURR_RELEASE,,}#" .gitreview
+       git submodule foreach git commit -asm "Update .gitreview to stable/${CURR_RELEASE,,}"
+       git submodule foreach 'git review -t ${CURR_RELEASE,,}-branch-cut'
+       sed -i -e "s#defaultbranch=master#defaultbranch=stable/${CURR_RELEASE,,}#" .gitreview
+       git add .gitreview
+       git commit -s -v -m "Update .gitreview to stable/${CURR_RELEASE,,}"
+       git review -t  ${CURR_RELEASE,,}-branch-cut
 
-- Merge all version bump patches in the order of dependencies. **(Release Engineering Team)**
-- Re-enable submit permissions for registered users and disable elevated RE committer rights on gerrit. **(Helpdesk)**
-- Notify release list on branch cutting work completion. **(Release Engineering Team)**
+Version bump job (Autorelease)
+------------------------------
+Version bump can performed either through the job or manually.
+
+#. Start the autorelease-version-bump-${NEXT_RELEASE,,} job
+   **(Release Engineering Team)**
+
+   .. note::
+
+      Enabled BRANCH_CUT and disable DRY_RUN to run the job for branch cut
+      work-flow. The version bump job can be run only on the master branch.
+
+Manual steps to version bump (Autorelease)
+------------------------------------------
+
+#. Version bump master by x.(y+1).z. **(Release Engineering Team)**
+
+   .. code-block:: bash
+
+       git checkout master
+       git submodule foreach 'git checkout master'
+       pip install lftools
+       lftools version bump ${CURR_RELEASE}
+
+#. Make sure the version bump changes does not modify anything under scripts or pom.xml.
+   **(Release Engineering Team)**
+
+   .. code-block:: bash
+
+       git checkout pom.xml scripts/
+
+#. Push version bump master changes to gerrit. **(Release Engineering Team)**
+
+   .. code-block:: bash
+
+       git submodule foreach 'git commit -asm "Bump versions by x.(y+1).z for next dev cycle"'
+       git submodule foreach 'git review -t ${CURR_RELEASE,,}-branch-cut'