docs/release-process/branch-cutting.rst

   1 **************
   2 Branch Cutting
   3 **************
   4
   5 This page documents the current branch cutting tasks that are needed
   6 to be performed at RC0 and which team has the necessary permissions
   7 in order to perform the necessary task in Parentheses.
   8
   9 JJB (releng/builder)
  10 --------------------
  11
  12 #. Export ``${NEXT_RELEASE}`` and ``${CURR_RELEASE}`` with new and current release names.
  13    **(releng/builder committers)**
  14
  15    .. code-block:: bash
  16
  17       export CURR_RELEASE="Silicon"
  18       export NEXT_RELEASE="Phosphorus"
  19
  20 #. Run the script ``cut-branch-jobs.py`` to generate next release jobs.
  21    **(releng/builder committers)**
  22
  23    .. code-block:: bash
  24
  25       python scripts/cut-branch-jobs.py $CURR_RELEASE $NEXT_RELEASE jjb/
  26       pre-commit run --all-files
  27
  28    .. note:: ``pre-commit`` is necessary to adjust the formatting of the generated YAML.
  29
  30    This script changes JJB yaml files to insert the next release configuration
  31    by updating streams and branches where relevant. For example if ``master``
  32    is currently Silicon, the result of this script will update config blocks
  33    as follows:
  34
  35    Update multi-streams:
  36
  37    .. code-block:: yaml
  38
  39       stream:
  40         - Phosphorus:
  41             branch: master
  42         - Silicon:
  43             branch: stable/silicon
  44
  45    Insert project new blocks:
  46
  47    .. code-block:: yaml
  48
  49       - project:
  50           name: aaa-phosphorus
  51           jobs:
  52             - '{project-name}-verify-{stream}-{maven}-{jdks}'
  53           stream: phosphorus
  54           branch: master
  55
  56       - project:
  57           name: aaa-silicon
  58           jobs:
  59             - '{project-name}-verify-{stream}-{maven}-{jdks}'
  60           stream: silicon
  61           branch: stable/silicon
  62
  63 #. Review and submit the changes to releng/builder project.
  64    **(releng/builder committers)**
  65
  66 Autorelease
  67 -----------
  68
  69 #. Block submit permissions for registered users and elevate RE's committer
  70    rights on Gerrit.
  71    **(Helpdesk)**
  72
  73    .. figure:: images/gerrit-update-committer-rights.png
  74
  75    .. note::
  76
  77       Enable **Exclusive** checkbox for the submit button to override any existing permissions.
  78
  79 #. Enable create reference permissions on Gerrit for RE's to submit
  80    ``.gitreview`` patches.
  81    **(Helpdesk)**
  82
  83    .. figure:: images/gerrit-update-create-reference.png
  84
  85    .. note::
  86
  87       Enable Exclusive checkbox override any existing permissions.
  88
  89 #. Start the branch cut job or use the manual steps below for branch cutting autorelease. **(Release Engineering Team)**
  90 #. Start the version bump job or use the manual steps below for version bump autorelease. **(Release Engineering Team)**
  91 #. Merge all ``.gitreview`` patches submitted though the job or manually. **(Release Engineering Team)**
  92 #. Remove create reference permissions set on Gerrit for RE's. **(Helpdesk)**
  93 #. Merge all version bump patches in the order of dependencies. **(Release Engineering Team)**
  94 #. Re-enable submit permissions for registered users and disable elevated RE committer rights on Gerrit. **(Helpdesk)**
  95 #. Notify release list on branch cutting work completion. **(Release Engineering Team)**
  96
  97
  98 Branch cut job (Autorelease)
  99 ----------------------------
 100 Branch cutting can be performed either through the job or manually.
 101
 102 #. Start the autorelease-branch-cut job
 103    **(Release Engineering Team)**
 104
 105 Manual steps to branch cut (Autorelease)
 106 ----------------------------------------
 107
 108 #. Setup ``releng/autorelease`` repository.
 109    **(Release Engineering Team)**
 110
 111    .. code-block:: bash
 112
 113        git review -s
 114        git submodule foreach 'git review -s'
 115        git checkout master
 116        git submodule foreach 'git checkout master'
 117        git pull --rebase
 118        git submodule foreach 'git pull --rebase'
 119
 120 #. Enable create reference permissions on Gerrit for RE's to submit
 121    ``.gitreview`` patches.
 122    **(Helpdesk)**
 123
 124    .. figure:: images/gerrit-update-create-reference.png
 125
 126    .. note::
 127
 128       Enable Exclusive check-box override any existing permissions.
 129
 130 #. Create ``stable/${CURR_RELEASE}`` branches based on HEAD master.
 131    **(Release Engineering Team)**
 132
 133    .. code-block:: bash
 134
 135        git checkout -b stable/${CURR_RELEASE,,} origin/master
 136        git submodule foreach 'git checkout -b stable/${CURR_RELEASE,,} origin/master'
 137        git push gerrit stable/${CURR_RELEASE,,}
 138        git submodule foreach 'git push gerrit stable/${CURR_RELEASE,,}'
 139
 140 #. Contribute ``.gitreview`` updates to ``stable/${CURR_RELEASE,,}``.
 141    **(Release Engineering Team)**
 142
 143    .. code-block:: bash
 144
 145        git submodule foreach sed -i -e "s#defaultbranch=master#defaultbranch=stable/${CURR_RELEASE,,}#" .gitreview
 146        git submodule foreach git commit -asm "Update .gitreview to stable/${CURR_RELEASE,,}"
 147        git submodule foreach 'git review -t ${CURR_RELEASE,,}-branch-cut'
 148        sed -i -e "s#defaultbranch=master#defaultbranch=stable/${CURR_RELEASE,,}#" .gitreview
 149        git add .gitreview
 150        git commit -s -v -m "Update .gitreview to stable/${CURR_RELEASE,,}"
 151        git review -t  ${CURR_RELEASE,,}-branch-cut
 152
 153 Version bump job (Autorelease)
 154 ------------------------------
 155 Version bump can performed either through the job or manually.
 156
 157 #. Start the autorelease-version-bump-${NEXT_RELEASE,,} job
 158    **(Release Engineering Team)**
 159
 160    .. note::
 161
 162       Enabled BRANCH_CUT and disable DRY_RUN to run the job for branch cut
 163       work-flow. The version bump job can be run only on the master branch.
 164
 165 Manual steps to version bump (Autorelease)
 166 ------------------------------------------
 167
 168 #. Version bump master by x.(y+1).z. **(Release Engineering Team)**
 169
 170    .. code-block:: bash
 171
 172        git checkout master
 173        git submodule foreach 'git checkout master'
 174        pip install lftools
 175        lftools version bump ${CURR_RELEASE}
 176
 177 #. Make sure the version bump changes does not modify anything under scripts or pom.xml.
 178    **(Release Engineering Team)**
 179
 180    .. code-block:: bash
 181
 182        git checkout pom.xml scripts/
 183
 184 #. Push version bump master changes to Gerrit. **(Release Engineering Team)**
 185
 186    .. code-block:: bash
 187
 188        git submodule foreach 'git commit -asm "Bump versions by x.(y+1).z for next dev cycle"'
 189        git submodule foreach 'git review -t ${CURR_RELEASE,,}-branch-cut'
 190
 191 #. Merge the patches in order according to the merge-order.log file found
 192    in autorelease jobs. **(Release Engineering Team)**
 193
 194    .. note::
 195
 196       The version bump patches can be merged more quickly by performing a local
 197       build with ``mvn clean deploy -DskipTests`` to prime Nexus with the new
 198       version updates.
 199
 200 Documentation post branch tasks
 201 -------------------------------
 202
 203 #. Git remove all files/directories from the ``docs/release-notes/*`` directory.
 204    **(Release Engineering Team)**
 205
 206    .. code-block:: bash
 207
 208        git checkout master
 209        git rm -rf docs/release-notes/<project file and/or folder>
 210        git commit -sm "Reset release notes for next dev cycle"
 211        git review