|
|
| (45 intermediate revisions by 14 users not shown) |
| Line 1: |
Line 1: |
| − | __NOTOC__
| + | |
| | = Stable Branch = | | = Stable Branch = |
| − | The [https://launchpad.net/~openstack-stable-maint stable-maint team] manages the stable branch for [[OpenStack]] core projects with the support of the core developers of those projects and the release team.
| |
| − |
| |
| − | <<[[TableOfContents]]()>>
| |
| − |
| |
| − | == Overview ==
| |
| − | 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.
| |
| − |
| |
| − | Official point releases for each project are published from the branch as sufficient fixes accumulate on the branch.
| |
| − |
| |
| − | Note, that the Swift project is not included in this process because its regular releases are intended to be stable updates.
| |
| − |
| |
| − | The Essex branch (named stable/essex) is currently actively maintained. The [https://launchpad.net/~openstack-stable-maint/+members#active stable-maint] team monitors the master branch for suitable fixes and backports them. The team also reviews and approves backports proposed by other developers.
| |
| − |
| |
| − | The Diablo branch (named stable/diablo) is currently passively maintained. Fixes proposed to the branch will be approved by [https://launchpad.net/~openstack-diablo-maint/+members#active diablo-maint] if the issue is particularly serious. Security fixes are a good example of the kind of fixes which are appropriate for the Diablo branch at this point. The Diablo branch will reach End Of Life when Folsom is released.
| |
| − |
| |
| − | [[OpenStack]]'s stable branch policy borrows much from prior art. There are many projects which maintain such a branch and it's possible to build a picture of a rough consensus across these projects on how a stable branch should operate. One example of another project's policy is [http://github.com/torvalds/linux/blob/master/Documentation/stable_kernel_rules.txt the Linux kernel's stable_kernel_rules.txt].
| |
| − |
| |
| − | == Appropriate Fixes ==
| |
| − | Only a limited class of changes are appropriate for inclusion on the stable branch.
| |
| − |
| |
| − | A number of factors must be weighed when considering a change:
| |
| − |
| |
| − | * The risk of regression - even the tiniest changes carry some risk of breaking something and we really want to avoid regressions on the stable branch
| |
| − | * The user visible benefit - are we fixing something that users might actually notice and, if so, how important is it?
| |
| − | * 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 already merged onto master, unless the change simply does not make sense on master
| |
| − |
| |
| − | The stable-maint team need 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.
| |
| − |
| |
| − | Some types of changes are completely forbidden:
| |
| − |
| |
| − | * New features
| |
| − | * Changes to the external HTTP APIs
| |
| − | * Changes to Nova's internal AMQP API
| |
| − | * Changes to the notification definitions
| |
| − | * DB schema changes
| |
| − | * Incompatible config file changes
| |
| − |
| |
| − | == Gerrit ==
| |
| − | Each backported commit proposed to gerrit should be reviewed and +2ed by two stable-maint members before it is approved. Where a stable-maint member has backported a fix, a single other +2 is sufficient for approval.
| |
| − |
| |
| − | If unsure about a given fix, stable-maint members should consult with the appropriate core developers for a more detailed technical review.
| |
| − |
| |
| − | Existing core developers are greatly encouraged to join the stable-maint team in order to help with reviewing backports, judging their appropriateness for the stable branch and approving them.
| |
| − |
| |
| − | == Security Fixes ==
| |
| − | Fixes for embargoed security issues receive special treatment. These should be reviewed in advance of disclosure by core developers and stable-maint. At the time of co-ordinated public disclosure, the fix is proposed simulataneously to master and the stable branches and immediately approved.
| |
| − |
| |
| − | == Releases ==
| |
| − | When a project's stable branch accumulates a sufficient number of fixes, the stable-maint and release teams will work together publish a point release. See [[StableBranchRelease]] for details about how the 2011.3.1 release was prepared.
| |
| − |
| |
| − | == Joining the Team ==
| |
| − | We're really keen to add more folks to the stable-maint team to help out with reviews.
| |
| − |
| |
| − | 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.
| |
| − |
| |
| − | After doing reviews over a few weeks, [https://launchpad.net/~openstack-stable-maint/+contactuser email the team and ask to be added].
| |
| − |
| |
| − | == Workflow ==
| |
| − | === Proposing Fixes ===
| |
| − | Anyone can propose a cherry-pick to the stable-maint team.
| |
| − |
| |
| − | One way is that if a bug in launchpad looks like a good candidate for backporting - e.g. if it's a significant bug with the previous release - then just tagging it with 'essex-backport' will bring it to the attention of the maintainers e.g. [https://bugs.launchpad.net/nova/+bugs?field.tag=essex-backport for nova] and [https://bugs.launchpad.net/glance/+bugs?field.tag=essex-backport for glance]. The tag will be removed when the fix has been applied to the stable branch, or rejected as unsuitable.
| |
| − |
| |
| − | Alternatively, if you have the appropriate permissions you can nominate the bug for the essex series.
| |
| − |
| |
| − | If the patch you're proposing will not cherry-pick cleanly, you can help by resolving the conflicts yourself and proposing the resulting patch. You can use [https://github.com/openstack-ci/git-review git-review] to propose a change to the stable branch with:
| |
| − |
| |
| − |
| |
| − | <pre><nowiki>
| |
| − | git review stable/essex # or stable/diablo, if appropriate
| |
| − | </nowiki></pre>
| |
| − |
| |
| − |
| |
| − | Failing all that, just ping one of the team and mention that you think the bug/commit is a good candidate.
| |
| − |
| |
| − | === Email Notifications ===
| |
| − | If you want to be notified of these patches you can create a watch on this screen: https://review.openstack.org/#settings,projects with the settings:
| |
| − |
| |
| − |
| |
| − | <pre><nowiki>
| |
| − | Project Name: All-Projects
| |
| − | Only If: branch:stable/essex
| |
| − | </nowiki></pre>
| |
| − |
| |
| − | (or stable/diablo as appropriate) . Then check the "Email Notifications - New Changes" checkbox. That will cause gerrit to send an email whenever a matching change is proposed, and better yet, the change shows up in your 'watched changes' list in gerrit.
| |
| − |
| |
| − | See the docs for [https://review.openstack.org/#settings,projects Watched Projects] configuration and the [https://review.openstack.org/Documentation/user-search.html search syntax].
| |
| − |
| |
| − | === Change-Ids ===
| |
| − | When cherry-picking a commit, keep the original <code><nowiki>Change-Id</nowiki></code> and gerrit will show a separate review for the stable branch while still allowing you to use the <code><nowiki>Change-Id</nowiki></code> to see all the reviews associated with it. See [https://review.openstack.org/#q,Id75bdd6531acf492df4c8d96723b8303406bffe0,n,z this change as an example].
| |
| − |
| |
| − | === Stale .pyc Files From Migrations ===
| |
| − | Switching between master and diablo is a pain because you end up with .pyc files for migrations that exist only on master and diablo blows up when trying to run them. Delete them with:
| |
| − |
| |
| − | * $> rm -f nova/db/sqlalchemy/migrate_repo/versions/*.pyc
| |
| − |
| |
| − | === Reviewing Changes On Master ===
| |
| − | Try e.g.
| |
| − |
| |
| − |
| |
| − | <pre><nowiki>
| |
| − | $> git log --graph 2011.3..origin/master
| |
| − | </nowiki></pre>
| |
| − |
| |
| − | If you're looking at a sequence of commits on a branch which got merged into master and you want to see exactly what changes were merged in, then look at the merge commit:
| |
| − |
| |
| − |
| |
| − | <pre><nowiki>
| |
| − | commit f5f429bac6446db084ca3f5d86c64127a1e539f2
| |
| − | Merge: e95e923 f3fb16a
| |
| − | </nowiki></pre>
| |
| − |
| |
| − | and do:
| |
| − |
| |
| − |
| |
| − | <pre><nowiki>
| |
| − | $> git diff e95e923..f5f429b
| |
| − | </nowiki></pre>
| |
| − |
| |
| − | === Keeping Notes ===
| |
| − | When reviewing the master branch for candidates to backport, you probably want to keep notes on which commits do and don't look good for cherry-picking. Even if it's just a case of keeping track of which was the latest commit on master you reviewed. You may also be curious about another maintainers opinion on a given patch.
| |
| − |
| |
| − | <code><nowiki>git notes</nowiki></code> allows you to maintain notes on commits in the same git repository as the commits themselves. It's exactly what's needed here, but it can be a bit of a pain to use.
| |
| − |
| |
| − | To fetch my notes on nova, do:
| |
| − |
| |
| − |
| |
| − | <pre><nowiki>
| |
| − | $> git remote add markmc-notes git://github.com/markmc/nova.git
| |
| − | $> git config remote.markmc-notes.fetch +refs/notes/diablo-notes:refs/notes/markmc/diablo-notes
| |
| − | $> git fetch markmc-notes
| |
| − | </nowiki></pre>
| |
| − |
| |
| − | You now have my notes in <code><nowiki>ref/notes/markmc/diablo-notes</nowiki></code>. To look at them, do either:
| |
| − |
| |
| − |
| |
| − | <pre><nowiki>
| |
| − | $> git log --notes=markmc/diablo-notes
| |
| − | </nowiki></pre>
| |
| − |
| |
| − | Or:
| |
| − |
| |
| − |
| |
| − | <pre><nowiki>
| |
| − | $> export GIT_NOTES_DISPLAY_REF=refs/notes/markmc/diablo-notes
| |
| − | $> git log
| |
| − | </nowiki></pre>
| |
| − |
| |
| − | You'll see something like:
| |
| − |
| |
| − |
| |
| − | <pre><nowiki>
| |
| − | commit 1b7fba648aa3eb4cdda345237c9f77dc0b229329
| |
| − | Author: Naveed Massjouni [...]
| |
| − | Date: Wed Oct 26 14:32:48 2011 -0400
| |
| − |
| |
| − | Adding support for retrying glance image downloads.
| |
| − |
| |
| − | Change-Id: Ifff40d90f7dc61a6d41ae2d6908d6e1e6f0aea7e
| |
| − |
| |
| − | Notes (markmc/diablo-notes):
| |
| − | New feature.
| |
| − |
| |
| − | Action: pass
| |
| − | </nowiki></pre>
| |
| − |
| |
| − | (The values of this Action tag I'm using are: pass = "Don't cherry-pick", pick = "Do cherry-pick", proposed = "Already cherry-picked and proposed in gerrit", merged = "Already cherry-picked and merged into stable" and defer = "Consider cherry-picking later")
| |
| − |
| |
| − | If you want to start maintaining your own notes, you can do e.g.
| |
| − |
| |
| − |
| |
| − | <pre><nowiki>
| |
| − | $> export GIT_NOTES_REF=refs/notes/diablo-notes
| |
| − | $> git notes add 261b4111d4
| |
| − | $> git notes edit 261b4111d4
| |
| − | $> git notes show 261b4111d4
| |
| − | $> git show 261b4111d4
| |
| − | </nowiki></pre>
| |
| − |
| |
| − | and to push them to a remote repo:
| |
| − |
| |
| | | | |
| − | <pre><nowiki>
| + | [http://docs.openstack.org/project-team-guide/stable-branches.html The stable branch policy is now maintained in the project team guide] |
| − | $> git push ${myrepo} refs/notes/diablo-notes:refs/notes/diablo-notes
| |
| − | </nowiki></pre>
| |
