From 74fb1e795ddc4c42c4db27ddb7f3c24e0a6bf8e3 Mon Sep 17 00:00:00 2001 From: ulik Date: Fri, 29 Jan 2016 16:29:48 +0100 Subject: Update stable-branch document according to the agreed version in wiki Jira: OCTO-106 Adjust the version of stable-branch to be equal to the wiki Change-Id: I3ab427ecf3c50bff7bf4b09d7369c13b5889223c Signed-off-by: ulik --- .../octopus_docs/images/stability_screenshot10.png | Bin 0 -> 58979 bytes .../octopus_docs/images/stability_screenshot11.png | Bin 0 -> 60369 bytes docs/octopus_docs/images/stability_screenshot9.png | Bin 0 -> 49489 bytes docs/octopus_docs/opnfv-stablebranch.rst | 152 +++++++-------------- 4 files changed, 47 insertions(+), 105 deletions(-) create mode 100644 docs/octopus_docs/images/stability_screenshot10.png create mode 100644 docs/octopus_docs/images/stability_screenshot11.png create mode 100644 docs/octopus_docs/images/stability_screenshot9.png (limited to 'docs/octopus_docs') diff --git a/docs/octopus_docs/images/stability_screenshot10.png b/docs/octopus_docs/images/stability_screenshot10.png new file mode 100644 index 0000000..da246d8 Binary files /dev/null and b/docs/octopus_docs/images/stability_screenshot10.png differ diff --git a/docs/octopus_docs/images/stability_screenshot11.png b/docs/octopus_docs/images/stability_screenshot11.png new file mode 100644 index 0000000..9778b58 Binary files /dev/null and b/docs/octopus_docs/images/stability_screenshot11.png differ diff --git a/docs/octopus_docs/images/stability_screenshot9.png b/docs/octopus_docs/images/stability_screenshot9.png new file mode 100644 index 0000000..b82b38a Binary files /dev/null and b/docs/octopus_docs/images/stability_screenshot9.png differ diff --git a/docs/octopus_docs/opnfv-stablebranch.rst b/docs/octopus_docs/opnfv-stablebranch.rst index eaed4cb..1dce7e0 100644 --- a/docs/octopus_docs/opnfv-stablebranch.rst +++ b/docs/octopus_docs/opnfv-stablebranch.rst @@ -1,16 +1,9 @@ ============= Stable Branch ============= -This document describes the way of working with stable branches and doing maintenance. -The page is derived from https://wiki.openstack.org/wiki/StableBranch , simplified and adapted to OPNFV. - -It was discussed on TSC on June 30, 2015 with minor comments. - -At this time only Arno release maintenance is covered. - -Overview --------- +Overview of Stable Branch Handling +---------------------------------- The stable branch is intended to be a safe source of fixes for high impact bugs and security issues which have been fixed on master since a given release. @@ -19,14 +12,15 @@ It allows users of release (stable) versions to benefit from the ongoing bugfix Official point releases for each project are published from the branch on a per need basis, as decided by the TSC. In later stages, a regular cadence for point releases may be introduced. -It's possible to check current maintained versions in the releases page. At this time only Arno is maintained. +It's possible to check current maintained versions in the releases page. -OPNFV's stable branch policy borrows much from prior art, in particular from OpenStack. +OPNFV's stable branch policy borrows much from prior art, in particular from OpenStack +and OpenDaylight. In general all fixes should be made on the main branch and cherry picked to stable. If there is a case where the fix is not able to be merged backwards only then we would need to do any work directly on stable. -The documented method for getting a fix into stable should be by a cherry-pick process. +The documented method for getting a fix into stable should be by a **cherry-pick process**. Stable branch policy -------------------- @@ -45,27 +39,13 @@ A number of factors must be weighed when considering a change: - **How self-contained the fix is** - if it fixes a significant issue but also refactors a lot of code, it's probably worth thinking about what a less risky fix might look like -- Whether the fix is **already on master - a change must be a **backport** of a change +- Whether the fix is **already on master** - a change must be a **backport** of a change already merged onto master, unless the change simply does not make sense on master (e.g. because of a change of architecture). - If there is a suitable **work-around** for a bug, normally there won't be a fix on stable. -- Since OPNFV is using several upstream projects, typically fixes in the upstream projects -will apply as fixes for OPNFV. Therefore complete **maintenance revisions of the upstream projects** -(i.e. minor versions) can be used as suitable backports for OPNFV maintenance releases. -- Since OPNFV is a midstream integration effort, also test cases might be suitable backports +- Since OPNFV is a midstream integration effort, also **test cases** might be suitable backports in case they are related to critical bugs found in stable. -Rules to maintain multiple versions and exceptions will be added later. - -The stable-mtc team needs to balance the risk of any given patch with the value -that it will provide to users of the stable branch. -A large, risky patch for a major data corruption issue might make sense. -As might a trivial fix for a fairly obscure error handling case. - -The stable-mtc team also will handle exceptions, -of which the most common will be that a fix on stable needs to be different to -the fix on master due to some other changes on master (e.g. architectural). - Some types of changes are completely forbidden: - New features @@ -84,12 +64,11 @@ Support phases will be introduced at a later time Review of fixes ~~~~~~~~~~~~~~~ -Each backported commit proposed to gerrit should be reviewed and +2ed by two -Arno-stable-maint members before it is approved. -Where a stable-maint member has backported a fix, a single other +2 is sufficient for approval. +Each backported commit proposed to gerrit should be reviewed and +2ed by committer(s) of the +corresponding projects. -If unsure about the technical details of a given fix, stable-maint members should consult with -the appropriate developers from the affected projects for a more detailed technical review. +If unsure about the technical details of a given fix, contributors should consult with +the committers from the affected projects for a more detailed technical review. If unsure if a fix is appropriate for the stable branch, at this time the TSC will do the final decision. @@ -97,7 +76,7 @@ Security fixes ~~~~~~~~~~~~~~ Fixes for embargoed security issues receive special treatment. -These should be reviewed in advance of disclosure by committers and stable-maint. +These should be reviewed in advance of disclosure by committers. At the time of coordinated public disclosure, the fix is proposed simultaneously to master and the stable branches and immediately approved. @@ -107,31 +86,50 @@ Processes Proposing fixes ~~~~~~~~~~~~~~~ -Anyone can propose a cherry-pick to the stable-maint team. +Anyone can propose a cherry-pick to the project committers. One way is that if a bugfix on master looks like a good candidate for backporting - e.g. if it's a significant bug with the revious release - then just nominating the bug -for Arno maintenance will bring it to the attention of the maintainers. +for the maintenance will bring it to the attention of the maintainers. If you don't have the appropriate permissions to nominate the bug, then send an email via the user list. The best way to get the patch merged in timely manner is to send it backported by yourself. To do so, you may try to use "Cherry Pick To" button in Gerrit UI for the original patch in master. -Gerrit will take care of creating a new review, modifying commit message to include 'cherry-picked from …' line etc. +Gerrit will take care of creating a new review, modifying commit message to include 'cherry-picked from ...' line etc. If the patch you're proposing will not cherry-pick cleanly, you can help by resolving the conflicts yourself and proposing the resulting patch. Please keep Conflicts lines in the commit message to help reviewers! -You can use git-review to propose a change to the stable branch with:: +You can use git-review to propose a change to the stable branch with: + +**Cherry Pick Patches from Master to a Stability Branch From Command Line**:: - $> git log (find out the commit id of the patch that you want to backport from "git log" output) $> git checkout stable/arno $> git cherry-pick -x $master_commit_d $> git review stable/arno -Note: cherry-pick -x option includes 'cherry-picked from …' line +Note: cherry-pick -x option includes 'cherry-picked from ...' line in the commit message which is required to avoid Gerrit bug +**Cherry Pick Patches from Master to a Stability Branch via Gerrit UI** + +1. Select the patch that you want to cherry pick from Master to Stable Branch +2. Locate the Cherry Pick To button + +.. image:: images/stability_screenshot9.png + :scale: 100% + +3. Start to type in "re" in the branch text box to get suggestions to appear, then select "refs/heads/stable/" + +.. image:: images/stability_screenshot10.png + :scale: 100% + +4. Click Cherry Pick Change + +.. image:: images/stability_screenshot11.png + :scale: 100% + Failing all that, just ping one of the team and mention that you think the bug/commit is a good candidate. Change-Ids @@ -154,7 +152,7 @@ click "Watched Projects" Project Name: All-Projects -Only If: branch:stable/arno +Only If: branch: Then check the "Email Notifications - New Changes" checkbox. That will cause gerrit to send an email whenever a matching change is proposed, @@ -168,78 +166,22 @@ will be introduced when we see the need. CI Pipeline ~~~~~~~~~~~ -For Arno release the jobs will be run once per day per installer (Fuel and Foreman) on stable/arno branch. -Since this is in addition to the jobs for master branch and jobs have long run time, -this might need re-evaluation as we go on. - -The artifacts arno/stable jobs produced are stored in the new directoies on artifacts.opnfv.org. - -The artifacts produced by daily jobs would be stored - For stable/arno, the storage locations will be /arno/.iso -The docs produced by daily and merge jobs would be stored - For stable/arno, the storage locations will be /arno/docs/ - -No changes in overall functionality in merge and verify jobs: they will continue doing builds only :: - - genesis-fuel-verify-master, genesis-fuel-verify-stable-arno, - genesis-fuel-merge-master, genesis-fuel-merge-stable-arno, - genesis-foreman-verify-master, genesis-foreman-verify-stable-arno, - genesis-foreman-merge-master, genesis-foreman-merge-stable-arno - - -Team organization ------------------ - -Project specific tasks -~~~~~~~~~~~~~~~~~~~~~~ - -Each of the 5 projects that contributed to Arno will dedicate some committers -which would be in charge of reviewing backports for their project, following the stable branch policy. -It is in the responsibility of each project how to select those committers (e.g. vote in the team). - -The group of these committers here are sometimes called the -"stable branch maintenance team" or "stable-mtc" without this being necessarily a team with own organization. - -Stable branch management -~~~~~~~~~~~~~~~~~~~~~~~~ +Octopus team will setup separate pipeline for stable branches. -Stable branches are less exercised than master branches, and they may get broken by external events. -Therefore a group of committers, the "stable branch maintenance team" (stable-mtc) is -tasked with specific stable branch support, -making sure the branch stays in good shape and remains usable at all times. -They monitor periodic jobs failures and enlist the help of others in order to fix the branches in case of breakage. -They should also raise flags if for some reason they are blocked and don't receive enough support, -in which case early abandon of the branch will be considered. +Stable Branch Maintenance Team organization +------------------------------------------- -The stable-mtc is responsible for the enforcement of the Stable Branch policy. -Initially it is composed of a release manager and at least one committer of each of the participating projects -and will have similar organization and rights as OPNFV project teams. -It will be granting exceptions for all questionable backports raised by projects, -providing backports reviews help everywhere, and educating projects members on the stable branch policy. +TBD. -The stable-mtc will propose to TSC to decide on point releases from the stable branch. -Preparation of the point release will be described in a second step. -The stable-mtc can also propose to TSC to decide to abandon maintenance of the release. +References +---------- -When a new OPNFV version is released, a stable-mtc team for that project will start. -At that time, the earlier maintenance version will go to a phase with less support. Details will be defined later. -Joining the team -~~~~~~~~~~~~~~~~ -Existing committers are greatly encouraged to join the stable-mtc in order to help with reviewing backports, -judging their appropriateness for the stable branch and approving them. +https://wiki.openstack.org/wiki/StableBranch -We're really keen to add more folks to the stable Arno stable-mtc to help out with reviews. +https://wiki.opendaylight.org/view/Simultaneous_Release:Cutting_Stability_Branches -All you really need is some time and the ability to apply the "safe source of high impact fixes" -and "must be fixed on master first" policies. -It mostly comes down to having a good sense of the risk vs benefit of applying a backport to the branch. -If you'd like to join the team, you can start by simply [+-]1ing stable branch reviews. -It's best if you can add some brief thoughts to your review on -why you think the fix is suitable for stable so that we know how you're applying the policy. -Same as in normal OPNFV projects, stable-mtc team will use committer votes for -some decisions like proposing a new point release to TSC. -- cgit 1.2.3-korg