|
|
(52 intermediate revisions by 15 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.
| + | [http://docs.openstack.org/project-team-guide/stable-branches.html The stable branch policy is now maintained in the project team guide] |
− | | |
− | <<[[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.
| |
− | | |
− | The Diablo branch (named stable/diablo) is currently passively maintained. Fixes proposed to the branch will be approved by stable-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.
| |
− | | |
− | The Essex branch (named stable/essex) is currently actively maintained. The stable-maint team monitors the master branch for suitable fixes and backports them. The team also reviews and approves backports proposed by other developers.
| |
− | | |
− | [[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
| |
− | * 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 ==
| |
− | | |
− | If you think you've got what it takes to apply these rules, do a few reviews and [https://launchpad.net/~openstack-stable-maint apply for membership]. All you need is an understanding of this policy and reasonable judgement, it's not rocket science!
| |
− | == Workflow ==
| |
− | | |
− | === Proposing Fixes ===
| |
− | | |
− | Anyone can propose a cherry-pick to the maintainers. This helps ensure that the maintainers don't miss anything. To catch the maintainers attention, simply add
| |
− | | |
− | | |
− | <pre><nowiki>
| |
− | Cc: stable-maintainers
| |
− | </nowiki></pre>
| |
− | | |
− | | |
− | to the commit message. 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/diablo
| |
− | </nowiki></pre>
| |
− | | |
− | | |
− | 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 'diablo-backport' will bring it to the attention of the maintainers e.g. [https://bugs.launchpad.net/nova/+bugs?field.tag=diablo-backport for nova] and [https://bugs.launchpad.net/glance/+bugs?field.tag=diablo-backport for glance]. The tag will be removed when the fix has been applied to the stable branch, or rejected as unsuitable.
| |
− | | |
− | === 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: message:"stable-maintainers"
| |
− | </nowiki></pre>
| |
− | | |
− | | |
− | And 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>
| |
− | $> git push ${myrepo} refs/notes/diablo-notes:refs/notes/diablo-notes
| |
− | </nowiki></pre>
| |