docs/octopus_docs/opnfv-stablebranch.rst

   1 =============
   2 Stable Branch
   3 =============
   4
   5 Overview of Stable Branch Handling
   6 ----------------------------------
   7
   8 The stable branch is intended to be a safe source of fixes for high impact bugs and security issues
   9 which have been fixed on master since a given release.
  10 It allows users of release (stable) versions to benefit from the ongoing bugfix work after the release.
  11
  12 Official point releases for each project are published from the branch on a per need basis, as decided by the TSC.
  13 In later stages, a regular cadence for point releases may be introduced.
  14
  15 It's possible to check current maintained versions in the releases page.
  16
  17 OPNFV's stable branch policy borrows much from prior art, in particular from OpenStack
  18 and OpenDaylight.
  19
  20 In general all fixes should be made on the main branch and cherry picked to stable.
  21 If there is a case where the fix is not able to be merged backwards
  22 only then we would need to do any work directly on stable.
  23 The documented method for getting a fix into stable should be by a **cherry-pick process**.
  24
  25 Stable branch policy
  26 --------------------
  27
  28 Appropriate fixes
  29 ~~~~~~~~~~~~~~~~~
  30
  31 Only a limited class of changes are appropriate for inclusion on the stable branch.
  32
  33 A number of factors must be weighed when considering a change:
  34
  35 - **The risk of regression** - even the tiniest changes carry some risk of
  36   breaking something and we really want to avoid regressions on the stable branch
  37 - **The user visible benefit** - are we fixing something that users might actually
  38   notice and, if so, how important is it?
  39 - **How self-contained the fix is** - if it fixes a significant issue but also
  40   refactors a lot of code, it's probably worth thinking about what a less risky
  41   fix might look like
  42 - Whether the fix is **already on master** - a change must be a **backport** of a change
  43   already merged onto master, unless the change simply does not make sense on master
  44   (e.g. because of a change of architecture).
  45 - If there is a suitable **work-around** for a bug, normally there won't be a fix on stable.
  46 - Since OPNFV is a midstream integration effort, also **test cases** might be suitable backports
  47   in case they are related to critical bugs found in stable.
  48
  49 Some types of changes are completely forbidden:
  50
  51 - New features
  52 - Changes to the external APIs
  53 - Changes to the notification definitions
  54 - DB schema changes
  55 - Incompatible config file changes
  56 - Changes including a version upgrade of an upstream component of OPNFV
  57   (since this will typically violate the above points)
  58
  59 Support phases
  60 ~~~~~~~~~~~~~~
  61
  62 Support phases will be introduced at a later time
  63
  64 Review of fixes
  65 ~~~~~~~~~~~~~~~
  66
  67 Each backported commit proposed to gerrit should be reviewed and +2ed by committer(s) of the
  68 corresponding projects.
  69
  70 If unsure about the technical details of a given fix, contributors should consult with
  71 the committers from the affected projects for a more detailed technical review.
  72
  73 If unsure if a fix is appropriate for the stable branch, at this time the TSC will do the final decision.
  74
  75 Security fixes
  76 ~~~~~~~~~~~~~~
  77
  78 Fixes for embargoed security issues receive special treatment.
  79 These should be reviewed in advance of disclosure by committers.
  80 At the time of coordinated public disclosure,
  81 the fix is proposed simultaneously to master and the stable branches and immediately approved.
  82
  83 Processes
  84 ---------
  85
  86 Proposing fixes
  87 ~~~~~~~~~~~~~~~
  88
  89 Anyone can propose a cherry-pick to the project committers.
  90
  91 One way is that if a bugfix on master looks like a good candidate for backporting
  92 - e.g. if it's a significant bug with the revious release - then just nominating the bug
  93 for the maintenance will bring it to the attention of the maintainers.
  94
  95 If you don't have the appropriate permissions to nominate the bug, then send an email via the user list.
  96
  97 The best way to get the patch merged in timely manner is to send it backported by yourself.
  98 To do so, you may try to use "Cherry Pick To" button in Gerrit UI for the original patch in master.
  99 Gerrit will take care of creating a new review, modifying commit message to include 'cherry-picked from ...' line etc.
 100
 101 If the patch you're proposing will not cherry-pick cleanly,
 102 you can help by resolving the conflicts yourself and proposing the resulting patch.
 103 Please keep Conflicts lines in the commit message to help reviewers!
 104 You can use git-review to propose a change to the stable branch with:
 105
 106 **Cherry Pick Patches from Master to a Stability Branch From Command Line**::
 107
 108    $> git checkout stable/arno
 109    $> git cherry-pick -x $master_commit_d
 110    $> git review stable/arno
 111
 112 Note: cherry-pick -x option includes 'cherry-picked from ...' line
 113 in the commit message which is required to avoid Gerrit bug
 114
 115 **Cherry Pick Patches from Master to a Stability Branch via Gerrit UI**
 116
 117 1. Select the patch that you want to cherry pick from Master to Stable Branch
 118 2. Locate the Cherry Pick To button
 119
 120 .. image:: images/stability_screenshot9.png
 121    :scale: 100%
 122
 123 3. Start to type in "re" in the branch text box to get suggestions to appear, then select "refs/heads/stable/<release-name>"
 124
 125 .. image:: images/stability_screenshot10.png
 126    :scale: 100%
 127
 128 4. Click Cherry Pick Change
 129
 130 .. image:: images/stability_screenshot11.png
 131    :scale: 100%
 132
 133 Failing all that, just ping one of the team and mention that you think the bug/commit is a good candidate.
 134
 135 Change-Ids
 136 ~~~~~~~~~~
 137
 138 When cherry-picking a commit, keep the original Change-Id and gerrit will
 139 show a separate review for the stable branch
 140 while still allowing you to use the Change-Id to see all the reviews associated with it.
 141
 142 Hint: Change-Id line must be in the last paragraph. Conflicts in the backport: add a new paragraph,
 143 creating a new Change-Id but you can avoid that by moving conflicts
 144 above the paragraph with Change-Id line or removing empty lines to make a single paragraph.
 145
 146 Email Notifications
 147 ~~~~~~~~~~~~~~~~~~~
 148
 149 If you want to be notified of these patches you can create a watch on this screen:
 150 https://gerrit.opnfv.org/gerrit/#/settings/projects
 151 click "Watched Projects"
 152
 153 Project Name: All-Projects
 154
 155 Only If: branch:<stable branch of your choice>
 156
 157 Then check the "Email Notifications - New Changes" checkbox.
 158 That will cause gerrit to send an email whenever a matching change is proposed,
 159 and better yet, the change shows up in your 'watched changes' list in gerrit.
 160
 161 Bug Tags
 162 ~~~~~~~~
 163
 164 will be introduced when we see the need.
 165
 166 CI Pipeline
 167 ~~~~~~~~~~~
 168
 169 Octopus team will setup separate pipeline for stable branches.
 170
 171
 172 Stable Branch Maintenance Team organization
 173 -------------------------------------------
 174
 175 TBD.
 176
 177 References
 178 ----------
 179
 180
 181
 182 https://wiki.openstack.org/wiki/StableBranch
 183
 184 https://wiki.opendaylight.org/view/Simultaneous_Release:Cutting_Stability_Branches
 185
 186
 187