docs/octopus_docs/opnfv-stablebranch.rst

   1 =============
   2 Stable Branch
   3 =============
   4 This document describes the way of working with stable branches and doing maintenance.
   5
   6 The page is derived from https://wiki.openstack.org/wiki/StableBranch , simplified and adapted to OPNFV.
   7
   8 It was discussed on TSC on June 30, 2015 with minor comments.
   9
  10 At this time only Arno release maintenance is covered.
  11
  12 Overview
  13 --------
  14
  15 The stable branch is intended to be a safe source of fixes for high impact bugs and security issues
  16 which have been fixed on master since a given release.
  17 It allows users of release (stable) versions to benefit from the ongoing bugfix work after the release.
  18
  19 Official point releases for each project are published from the branch on a per need basis, as decided by the TSC.
  20 In later stages, a regular cadence for point releases may be introduced.
  21
  22 It's possible to check current maintained versions in the releases page. At this time only Arno is maintained.
  23
  24 OPNFV's stable branch policy borrows much from prior art, in particular from OpenStack.
  25
  26 In general all fixes should be made on the main branch and cherry picked to stable.
  27 If there is a case where the fix is not able to be merged backwards
  28 only then we would need to do any work directly on stable.
  29 The documented method for getting a fix into stable should be by a cherry-pick process.
  30
  31 Stable branch policy
  32 --------------------
  33
  34 Appropriate fixes
  35 ~~~~~~~~~~~~~~~~~
  36
  37 Only a limited class of changes are appropriate for inclusion on the stable branch.
  38
  39 A number of factors must be weighed when considering a change:
  40
  41 - **The risk of regression** - even the tiniest changes carry some risk of
  42   breaking something and we really want to avoid regressions on the stable branch
  43 - **The user visible benefit** - are we fixing something that users might actually
  44   notice and, if so, how important is it?
  45 - **How self-contained the fix is** - if it fixes a significant issue but also
  46   refactors a lot of code, it's probably worth thinking about what a less risky
  47   fix might look like
  48 - Whether the fix is **already on master - a change must be a **backport** of a change
  49   already merged onto master, unless the change simply does not make sense on master
  50   (e.g. because of a change of architecture).
  51 - If there is a suitable **work-around** for a bug, normally there won't be a fix on stable.
  52 - Since OPNFV is using several upstream projects, typically fixes in the upstream projects
  53 will apply as fixes for OPNFV. Therefore complete **maintenance revisions of the upstream projects**
  54 (i.e. minor versions) can be used as suitable backports for OPNFV  maintenance releases.
  55 - Since OPNFV is a midstream integration effort, also test cases might be suitable backports
  56   in case they are related to critical bugs found in stable.
  57
  58 Rules to maintain multiple versions and exceptions will be added later.
  59
  60 The stable-mtc team needs to balance the risk of any given patch with the value
  61 that it will provide to users of the stable branch.
  62 A large, risky patch for a major data corruption issue might make sense.
  63 As might a trivial fix for a fairly obscure error handling case.
  64
  65 The stable-mtc team also will handle exceptions,
  66 of which the most common will be that a fix on stable needs to be different to
  67 the fix on master due to some other changes on master (e.g. architectural).
  68
  69 Some types of changes are completely forbidden:
  70
  71 - New features
  72 - Changes to the external APIs
  73 - Changes to the notification definitions
  74 - DB schema changes
  75 - Incompatible config file changes
  76 - Changes including a version upgrade of an upstream component of OPNFV
  77   (since this will typically violate the above points)
  78
  79 Support phases
  80 ~~~~~~~~~~~~~~
  81
  82 Support phases will be introduced at a later time
  83
  84 Review of fixes
  85 ~~~~~~~~~~~~~~~
  86
  87 Each backported commit proposed to gerrit should be reviewed and +2ed by two
  88 Arno-stable-maint members before it is approved.
  89 Where a stable-maint member has backported a fix, a single other +2 is sufficient for approval.
  90
  91 If unsure about the technical details of a given fix, stable-maint members should consult with
  92 the appropriate developers from the affected projects for a more detailed technical review.
  93
  94 If unsure if a fix is appropriate for the stable branch, at this time the TSC will do the final decision.
  95
  96 Security fixes
  97 ~~~~~~~~~~~~~~
  98
  99 Fixes for embargoed security issues receive special treatment.
 100 These should be reviewed in advance of disclosure by committers and stable-maint.
 101 At the time of coordinated public disclosure,
 102 the fix is proposed simultaneously to master and the stable branches and immediately approved.
 103
 104 Processes
 105 ---------
 106
 107 Proposing fixes
 108 ~~~~~~~~~~~~~~~
 109
 110 Anyone can propose a cherry-pick to the stable-maint team.
 111
 112 One way is that if a bugfix on master looks like a good candidate for backporting
 113 - e.g. if it's a significant bug with the revious release - then just nominating the bug
 114 for Arno maintenance will bring it to the attention of the maintainers.
 115
 116 If you don't have the appropriate permissions to nominate the bug, then send an email via the user list.
 117
 118 The best way to get the patch merged in timely manner is to send it backported by yourself.
 119 To do so, you may try to use "Cherry Pick To" button in Gerrit UI for the original patch in master.
 120 Gerrit will take care of creating a new review, modifying commit message to include 'cherry-picked from \85' line etc.
 121
 122 If the patch you're proposing will not cherry-pick cleanly,
 123 you can help by resolving the conflicts yourself and proposing the resulting patch.
 124 Please keep Conflicts lines in the commit message to help reviewers!
 125 You can use git-review to propose a change to the stable branch with::
 126
 127    $> git log (find out the commit id of the patch that you want to backport from "git log" output)
 128    $> git checkout stable/arno
 129    $> git cherry-pick -x $master_commit_d
 130    $> git review stable/arno
 131
 132 Note: cherry-pick -x option includes 'cherry-picked from \85' line
 133 in the commit message which is required to avoid Gerrit bug
 134
 135 Failing all that, just ping one of the team and mention that you think the bug/commit is a good candidate.
 136
 137 Change-Ids
 138 ~~~~~~~~~~
 139
 140 When cherry-picking a commit, keep the original Change-Id and gerrit will
 141 show a separate review for the stable branch
 142 while still allowing you to use the Change-Id to see all the reviews associated with it.
 143
 144 Hint: Change-Id line must be in the last paragraph. Conflicts in the backport: add a new paragraph,
 145 creating a new Change-Id but you can avoid that by moving conflicts
 146 above the paragraph with Change-Id line or removing empty lines to make a single paragraph.
 147
 148 Email Notifications
 149 ~~~~~~~~~~~~~~~~~~~
 150
 151 If you want to be notified of these patches you can create a watch on this screen:
 152 https://gerrit.opnfv.org/gerrit/#/settings/projects
 153 click "Watched Projects"
 154
 155 Project Name: All-Projects
 156
 157 Only If: branch:stable/arno
 158
 159 Then check the "Email Notifications - New Changes" checkbox.
 160 That will cause gerrit to send an email whenever a matching change is proposed,
 161 and better yet, the change shows up in your 'watched changes' list in gerrit.
 162
 163 Bug Tags
 164 ~~~~~~~~
 165
 166 will be introduced when we see the need.
 167
 168 CI Pipeline
 169 ~~~~~~~~~~~
 170
 171 For Arno release the jobs will be run once per day per installer (Fuel and Foreman) on stable/arno branch.
 172 Since this is in addition to the jobs for master branch and jobs have long run time,
 173 this might need re-evaluation as we go on.
 174
 175 The artifacts arno/stable jobs produced are stored in the new directoies on artifacts.opnfv.org.
 176
 177 The artifacts produced by daily jobs would be stored
 178   For stable/arno, the storage locations will be <project_name>/arno/<artifact_name>.iso
 179 The docs produced by daily and merge jobs would be stored
 180   For stable/arno, the storage locations will be <project_name>/arno/docs/<document_name>
 181
 182 No changes in overall functionality in merge and verify jobs: they will continue doing builds only ::
 183
 184     genesis-fuel-verify-master, genesis-fuel-verify-stable-arno,
 185     genesis-fuel-merge-master, genesis-fuel-merge-stable-arno,
 186     genesis-foreman-verify-master, genesis-foreman-verify-stable-arno,
 187     genesis-foreman-merge-master, genesis-foreman-merge-stable-arno
 188
 189
 190 Team organization
 191 -----------------
 192
 193 Project specific tasks
 194 ~~~~~~~~~~~~~~~~~~~~~~
 195
 196 Each of the 5 projects that contributed to Arno will dedicate some committers
 197 which would be in charge of reviewing backports for their project, following the stable branch policy.
 198 It is in the responsibility of each project how to select those committers (e.g. vote in the team).
 199
 200 The group of these committers here are sometimes called the
 201 "stable branch maintenance team" or "stable-mtc" without this being necessarily a team with own organization.
 202
 203 Stable branch management
 204 ~~~~~~~~~~~~~~~~~~~~~~~~
 205
 206 Stable branches are less exercised than master branches, and they may get broken by external events.
 207
 208 Therefore a group of committers, the "stable branch maintenance team" (stable-mtc) is
 209 tasked with specific stable branch support,
 210 making sure the branch stays in good shape and remains usable at all times.
 211 They monitor periodic jobs failures and enlist the help of others in order to fix the branches in case of breakage.
 212 They should also raise flags if for some reason they are blocked and don't receive enough support,
 213 in which case early abandon of the branch will be considered.
 214
 215 The stable-mtc is responsible for the enforcement of the Stable Branch policy.
 216 Initially it is composed of a release manager and at least one committer of each of the participating projects
 217 and will have similar organization and rights as OPNFV project teams.
 218 It will be granting exceptions for all questionable backports raised by projects,
 219 providing backports reviews help everywhere, and educating projects members on the stable branch policy.
 220
 221 The stable-mtc will propose to TSC to decide on point releases from the stable branch.
 222 Preparation of the point release will be described in a second step.
 223 The stable-mtc can also propose to TSC to decide to abandon maintenance of the release.
 224
 225 When a new OPNFV version is released, a stable-mtc team for that project will start.
 226 At that time, the earlier maintenance version will go to a phase with less support. Details will be defined later.
 227
 228 Joining the team
 229 ~~~~~~~~~~~~~~~~
 230
 231 Existing committers are greatly encouraged to join the stable-mtc in order to help with reviewing backports,
 232 judging their appropriateness for the stable branch and approving them.
 233
 234 We're really keen to add more folks to the stable Arno stable-mtc to help out with reviews.
 235
 236 All you really need is some time and the ability to apply the "safe source of high impact fixes"
 237 and "must be fixed on master first" policies.
 238 It mostly comes down to having a good sense of the risk vs benefit of applying a backport to the branch.
 239
 240 If you'd like to join the team, you can start by simply [+-]1ing stable branch reviews.
 241 It's best if you can add some brief thoughts to your review on
 242 why you think the fix is suitable for stable so that we know how you're applying the policy.
 243
 244 Same as in normal OPNFV projects, stable-mtc team will use committer votes for
 245 some decisions like proposing a new point release to TSC.