|
|
| (65 intermediate revisions by 17 users not shown) |
| Line 1: |
Line 1: |
| − | __NOTOC__
| + | |
| | = Stable Branch = | | = Stable Branch = |
| | | | |
| − | At the Essex Design Summit it was agreed that a working group would be established to maintain stable/backport/fixes branches for the Diablo
| + | [http://docs.openstack.org/project-team-guide/stable-branches.html The stable branch policy is now maintained in the project team guide] |
| − | release.
| |
| − | | |
| − | This effort is essentially an experiment to establish:
| |
| − | | |
| − | * That the idea makes sense
| |
| − | * That there is enough people willing to help maintain it for it to be viable
| |
| − | * The policies for what belongs in such a stable branch
| |
| − | * How changes should be proposed to the branch
| |
| − | * The workflow for maintaining the branch
| |
| − | * Whether updates should be released from the branch
| |
| − | | |
| − | This page tries to cover most of these topics and should be considered an RFC.
| |
| − | | |
| − | == Overview ==
| |
| − | | |
| − | Each project will have a branch named after the previous release. For example, the stable branch for the diablo release will be called 'stable/diablo'.
| |
| − | | |
| − | The stable branch will only be maintained until the next release is out. This period may be extended if there are volunteers to maintain it beyond this point.
| |
| − | | |
| − | The maintainers, in conjunction with the release team, may choose to cut a new release from the branch if there are enough worthwhile fixes and the branch has been tested enough.
| |
| − | | |
| − | The branch maintainer(s) will monitor master for changes and periodically cherry-pick patches into the branch. They may choose to stop actively monitoring master after a period (e.g. 2 months) if they feel there are so few backport candidates that it is no longer worth the effort. If so, they will notify developers via the mailing list.
| |
| − | | |
| − | All changes to the stable branch will go through gerrit. The branch maintainers and core teams of each project can +2 the changes.
| |
| − | | |
| − | Every change on the stable branch must pass all the tests.
| |
| − | | |
| − | Security patches will follow a different process, whereby the patch can be embargoed and pushed at the same time as the patch on master, once the issue has been made public.
| |
| − | | |
| − | == Policy ==
| |
| − | | |
| − | The most obvious question we need to answer is "What belongs in a stable branch?"
| |
| − | | |
| − | However, we don't need to ignore prior art here. Plenty of projects maintain such a branch and there's a very rough consensus across projects on what the policy should be.
| |
| − | | |
| − | As an example, [http://github.com/torvalds/linux/blob/master/Documentation/stable_kernel_rules.txt stable_kernel_rules.txt] says:
| |
| − | | |
| − | * It must be obviously correct and tested.
| |
| − | * It cannot be bigger than 100 lines, with context.
| |
| − | * It must fix only one thing.
| |
| − | * It must fix a real bug that bothers people (not a, "This could be a problem..." type thing).
| |
| − | * It must fix a problem that causes a build error [..], an oops, a hang, data corruption, a real security issue, or some "oh, that's not good" issue. In short, something critical.
| |
| − | * No "theoretical race condition" issues, unless an explanation of how the race can be exploited is also provided.
| |
| − | * It cannot contain any "trivial" fixes in it (spelling changes, whitespace cleanups, etc).
| |
| − | * It or an equivalent fix must [...] (upstream).
| |
| − | | |
| − | We can also add some rules specific to [[OpenStack]]:
| |
| − | | |
| − | * No changes to the external HTTP APIs
| |
| − | * No changes to the internal AMQP API
| |
| − | * No DB schema changes
| |
| − | | |
| − | The branch is intended to be a safe source of fixes for significant issues which have been fixed on master since the release. New features, regressions, compatibility issues, subtle behavioural changes, etc. have no place here.
| |
| − | | |
| − | The maintainers 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.
| |
| − | | |
| − | == 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].
| |
| − | | |
| − | === 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.
| |
| − | | |
| − | == Random Notes and Tips ==
| |
| − | | |
| − | The maintainers need to be able to collaborate on the process of monitoring master for suitable fixes - e.g. you need to be able to record which commits you have reviewed, which commits you have rejected etc. Using git notes is one way we could do this. We need to experiment with them to see what works best. | |
| − | | |
| − | In Essex, the RBP will be when the RCs are considered "good enough". It is at that point the stable maintainers need to start monitoring master. For Diablo, the PTLs and release manager did this work. That implies that the PTLs and RM will initially take an active interest in the stable branch, but that interest will want after a time. Which makes perfect sense.
| |
| − | | |
| − | 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.
| |
| − | | |
| − | When cherry-picking a commit, in order to ensure a new Change-Id, you need to do:
| |
| − | | |
| − | | |
| − | <pre><nowiki>
| |
| − | $> git cherry-pick -e -x $commit
| |
| − | <remove the Change-Id tag>
| |
| − | $> git commit --amend
| |
| − | <this will add a new Change-Id>
| |
| − | </nowiki></pre>
| |
| − | | |
| − | | |
| − | Alternatively, you can skip the latter step and use 'git rebase -i' and the 'reword' action to add Change-Ids later.
| |
| − | | |
| − | We could probably fix this in the commit-msg hook ... perhaps by recognizing when its a cherry-pick. Or maybe there's a hook specific to cherry-picking.
| |
| − | | |
| − | Try 'git log --graph' ... I found it helpful when reviewing the changes on master since diablo.
| |
| − | | |
| − | 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>
| |
| − | | |
| − | | |
| − | You can use gerrit to notify you of commits matching a pattern. See the [https://review.openstack.org/#settings,projects Watched Projects] configuration and the [https://review.openstack.org/Documentation/user-search.html documentation for the search syntax]. We can use this to watch for commits with <code><nowiki>Cc: stable@openstack.org</nowiki></code>.
| |
