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. **(releng/builder committers)**
  64
  65 Autorelease
  66 -----------
  67
  68 #. Block submit permissions for registered users and elevate RE's committer rights on gerrit.
  69    **(Helpdesk)**
  70
  71    .. figure:: images/gerrit-update-committer-rights.png
  72
  73    .. note::
  74
  75       Enable **Exclusive** checkbox for the submit button to override any existing permissions.
  76
  77 #. Enable create reference permissions on gerrit for RE's to submit .gitreview patches.
  78    **(Helpdesk)**
  79
  80    .. figure:: images/gerrit-update-create-reference.png
  81
  82    .. note::
  83
  84       Enable Exclusive checkbox override any existing permissions.
  85
  86 #. Start the branch cut job or use the manual steps below for branch cutting autorelease. **(Release Engineering Team)**
  87 #. Start the version bump job or use the manual steps below for version bump autorelease. **(Release Engineering Team)**
  88 #. Merge all .gitreview patches submitted though the job or manually. **(Release Engineering Team)**
  89 #. Remove create reference permissions set on gerrit for RE's. **(Helpdesk)**
  90 #. Merge all version bump patches in the order of dependencies. **(Release Engineering Team)**
  91 #. Re-enable submit permissions for registered users and disable elevated RE committer rights on gerrit. **(Helpdesk)**
  92 #. Notify release list on branch cutting work completion. **(Release Engineering Team)**
  93
  94
  95 Branch cut job (Autorelease)
  96 ----------------------------
  97 Branch cutting can be performed either through the job or manually.
  98
  99 #. Start the autorelease-branch-cut job
 100    **(Release Engineering Team)**
 101
 102 Manual steps to branch cut (Autorelease)
 103 ----------------------------------------
 104
 105 #. Setup releng/autorelease repository.
 106    **(Release Engineering Team)**
 107
 108    .. code-block:: bash
 109
 110        git review -s
 111        git submodule foreach 'git review -s'
 112        git checkout master
 113        git submodule foreach 'git checkout master'
 114        git pull --rebase
 115        git submodule foreach 'git pull --rebase'
 116
 117 #. Enable create reference permissions on gerrit for RE's to submit .gitreview patches.
 118    **(Helpdesk)**
 119
 120    .. figure:: images/gerrit-update-create-reference.png
 121
 122    .. note::
 123
 124       Enable Exclusive check-box override any existing permissions.
 125
 126 #. Create stable/${CURR_RELEASE} branches based on HEAD master.
 127    **(Release Engineering Team)**
 128
 129    .. code-block:: bash
 130
 131        git checkout -b stable/${CURR_RELEASE,,} origin/master
 132        git submodule foreach 'git checkout -b stable/${CURR_RELEASE,,} origin/master'
 133        git push gerrit stable/${CURR_RELEASE,,}
 134        git submodule foreach 'git push gerrit stable/${CURR_RELEASE,,}'
 135
 136 #. Contribute .gitreview updates to stable/${CURR_RELEASE,,}.
 137    **(Release Engineering Team)**
 138
 139    .. code-block:: bash
 140
 141        git submodule foreach sed -i -e "s#defaultbranch=master#defaultbranch=stable/${CURR_RELEASE,,}#" .gitreview
 142        git submodule foreach git commit -asm "Update .gitreview to stable/${CURR_RELEASE,,}"
 143        git submodule foreach 'git review -t ${CURR_RELEASE,,}-branch-cut'
 144        sed -i -e "s#defaultbranch=master#defaultbranch=stable/${CURR_RELEASE,,}#" .gitreview
 145        git add .gitreview
 146        git commit -s -v -m "Update .gitreview to stable/${CURR_RELEASE,,}"
 147        git review -t  ${CURR_RELEASE,,}-branch-cut
 148
 149 Version bump job (Autorelease)
 150 ------------------------------
 151 Version bump can performed either through the job or manually.
 152
 153 #. Start the autorelease-version-bump-${NEXT_RELEASE,,} job
 154    **(Release Engineering Team)**
 155
 156    .. note::
 157
 158       Enabled BRANCH_CUT and disable DRY_RUN to run the job for branch cut
 159       work-flow. The version bump job can be run only on the master branch.
 160
 161 Manual steps to version bump (Autorelease)
 162 ------------------------------------------
 163
 164 #. Version bump master by x.(y+1).z. **(Release Engineering Team)**
 165
 166    .. code-block:: bash
 167
 168        git checkout master
 169        git submodule foreach 'git checkout master'
 170        pip install lftools
 171        lftools version bump ${CURR_RELEASE}
 172
 173 #. Make sure the version bump changes does not modify anything under scripts or pom.xml.
 174    **(Release Engineering Team)**
 175
 176    .. code-block:: bash
 177
 178        git checkout pom.xml scripts/
 179
 180 #. Push version bump master changes to gerrit. **(Release Engineering Team)**
 181
 182    .. code-block:: bash
 183
 184        git submodule foreach 'git commit -asm "Bump versions by x.(y+1).z for next dev cycle"'
 185        git submodule foreach 'git review -t ${CURR_RELEASE,,}-branch-cut'
 186
 187 #. Merge the patches in order according to the merge-order.log file found
 188    in autorelease jobs. **(Release Engineering Team)**
 189
 190    .. note::
 191
 192       The version bump patches can be merged more quickly by performing a local
 193       build with ``mvn clean deploy -DskipTests`` to prime Nexus with the new
 194       version updates.
 195
 196 Documentation post branch tasks
 197 -------------------------------
 198
 199 #. Git remove all files/directories from the ``docs/release-notes/*`` directory.
 200    **(Release Engineering Team)**
 201
 202    .. code-block:: bash
 203
 204        git checkout master
 205        git rm -rf docs/release-notes/<project file and/or folder>
 206        git commit -sm "Reset release notes for next dev cycle"
 207        git review