kienan
/
puppet-strings
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

(maint) Remove references to stable in COMMITTERS 

Since puppet strings is a very small project, at the moment we
don't need to maintain a master and a stable branch. As a result,
the COMMITTERS.md guide should not contain references to the stable
branch or include information around dealing with both the master
and stable branch. Remove these references so that COMMITTERS is
consistent with our approach to the strings repository.
This commit is contained in:
Hailee Kenney 2014-10-01 09:42:57 -07:00
parent 98a18660ef
commit 3c826a0ca8
1 changed files with 31 additions and 90 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

121
COMMITTERS.md
View File

@ -4,10 +4,9 @@ Committing changes to Strings
We would like to make it easier for community members to contribute to strings We would like to make it easier for community members to contribute to strings
using pull requests, even if it makes the task of reviewing and committing using pull requests, even if it makes the task of reviewing and committing
these changes a little harder. Pull requests are only ever based on a single these changes a little harder. Pull requests are only ever based on a single
branch, however, we maintain more than one active branch. As a result branch. As a result contributors should target their changes at the master branch.
contributors should target their changes at the master branch. This makes the This makes the process of contributing a little easier for the contributor since
process of contributing a little easier for the contributor since they don't they don't need to concern themselves with the question, "What branch do I base my changes
need to concern themselves with the question, "What branch do I base my changes
on?" This is already called out in the [CONTRIBUTING.md](http://goo.gl/XRH2J). on?" This is already called out in the [CONTRIBUTING.md](http://goo.gl/XRH2J).
Therefore, it is the responsibility of the committer to re-base the change set Therefore, it is the responsibility of the committer to re-base the change set
@ -18,11 +17,9 @@ effort to make sure the end users must opt-in to new behavior that is
incompatible with previous behavior. We employ the use of [feature incompatible with previous behavior. We employ the use of [feature
flags](http://stackoverflow.com/questions/7707383/what-is-a-feature-flag) as flags](http://stackoverflow.com/questions/7707383/what-is-a-feature-flag) as
the primary way to achieve this user opt-in behavior. Finally, it is the the primary way to achieve this user opt-in behavior. Finally, it is the
responsibility of the committer to make sure the `master` and `stable` branches responsibility of the committer to make sure the `master` branch
are both clean and working at all times. Clean means that dead code is not is clean and working at all times. Clean means that dead code is not
allowed, everything needs to be usable in some manner at all points in time. allowed, everything needs to be usable in some manner at all points in time.
Stable is not an indication of the build status, but rather an expression of
our intent that the `stable` branch does not receive new functionality.
The rest of this document addresses the concerns of the committer. This The rest of this document addresses the concerns of the committer. This
document will help guide the committer decide which branch to base, or re-base document will help guide the committer decide which branch to base, or re-base
@ -48,14 +45,10 @@ making the decision what base branch to merge the change set into.
**base branch** - A branch in Git that contains an active history of changes **base branch** - A branch in Git that contains an active history of changes
and will eventually be released using semantic version guidelines. The branch and will eventually be released using semantic version guidelines. The branch
named `master` will always exist as a base branch. The other base branches are named `master` will always exist as a base branch.
`stable`, and `security` described below.
**master branch** - The branch where new functionality that are not bug fixes **master branch** - The branch where new functionality that and bug fixes are
is merged. merged.
**stable branch** - The branch where bug fixes against the latest release or
release candidate are merged.
**security** - Where critical security fixes are merged. These change sets **security** - Where critical security fixes are merged. These change sets
will then be merged into release branches independently from one another. (i.e. will then be merged into release branches independently from one another. (i.e.
@ -67,7 +60,7 @@ per our security policy published at
Committer Guide Committer Guide
==== ====
This section provides a guide to follow while committing change sets to Puppet This section provides a guide to follow while committing change sets to strings
base branches. base branches.
How to decide what release(s) should be patched How to decide what release(s) should be patched
@ -78,8 +71,8 @@ branch that a change set should be merged into.
The latest minor release of a major release is the only base branch that should The latest minor release of a major release is the only base branch that should
be patched. These patches will be merged into `master` if they contain new be patched. These patches will be merged into `master` if they contain new
functionality. They will be merged into `stable` and `master` if they fix a functionality and if they fix a critical bug. Older minor releases in a major release
critical bug. Older minor releases in a major release do not get patched. do not get patched.
Before the switch to [semantic versions](http://semver.org/) committers did not Before the switch to [semantic versions](http://semver.org/) committers did not
have to think about the difference between minor and major releases. have to think about the difference between minor and major releases.
@ -94,41 +87,9 @@ security branch as the base branch. Please send all security related
information or patches to security@puppetlabs.com as per our [Security information or patches to security@puppetlabs.com as per our [Security
Policy](https://puppetlabs.com/security/). Policy](https://puppetlabs.com/security/).
The CI systems are configured to run against `master` and `stable`. Over time, The CI systems are configured to run against `master`. Over time, this branch
these branches will refer to different versions, but their name will remain will refer to different versions, but its name will remain fixed to avoid having
fixed to avoid having to update CI jobs and tasks as new versions are released. to update CI jobs and tasks as new versions are released.
How to commit a change set to multiple base branches
---
A change set may apply to multiple branches, for example a bug fix should be
applied to the stable release and the development branch. In this situation
the change set needs to be committed to multiple base branches. This section
provides a guide for how to merge patches into these branches, e.g.
`stable` is patched, how should the changes be applied to `master`?
First, rebase the change set onto the `stable` branch. Next, merge the change
set into the `stable` branch using a merge commit. Once merged into `stable`,
merge the same change set into `master` without doing a rebase as to preserve
the commit identifiers. This merge strategy follows the [git
flow](http://nvie.com/posts/a-successful-git-branching-model/) model. Both of
these change set merges should have a merge commit which makes it much easier
to track a set of commits as a logical change set through the history of a
branch. Merge commits should be created using the `--no-ff --log` git merge
options.
Any merge conflicts should be resolved using the merge commit in order to
preserve the commit identifiers for each individual change. This ensures `git
branch --contains` will accurately report all of the base branches which
contain a specific patch.
Using this strategy, the stable branch need not be reset. Both `master` and
`stable` have infinite lifetimes. Patch versions, also known as bug fix
releases, will be tagged and released directly from the `stable` branch. Major
and minor versions, also known as feature releases, will be tagged and released
directly from the `master` branch. Upon release of a new major or minor
version all of the changes in the `master` branch will be merged into the
`stable` branch.
Code review checklist Code review checklist
--- ---
@ -172,16 +133,11 @@ paying attention to our automated build tools.
Example Procedure Example Procedure
==== ====
This section helps a committer rebase a contribution onto an earlier base This section helps a committer rebase and merge a contribution into the base branch.
branch, then merge into the base branch and up through all active base
branches.
Suppose a contributor submits a pull request based on master. The change set Suppose a contributor submits a pull request based on master. The change set
fixes a bug reported against Puppet 3.1.1 which is the most recently released fixes a bug reported against strings 0.1.0 which is the most recently released
version of Puppet. version of strings.
In this example the committer should rebase the change set onto the `stable`
branch since this is a bug rather than new functionality.
First, the committer pulls down the branch using the `hub` gem. This tool First, the committer pulls down the branch using the `hub` gem. This tool
automates the process of adding the remote repository and creating a local automates the process of adding the remote repository and creating a local
@ -191,35 +147,21 @@ branch to track the remote branch.
Branch jeffmccune-pdoc-34_fix_foo_error set up to track remote branch pdoc-34-fix_foo_error from jeffmccune. Branch jeffmccune-pdoc-34_fix_foo_error set up to track remote branch pdoc-34-fix_foo_error from jeffmccune.
Switched to a new branch 'jeffmccune-pdoc-34_fix_foo_error' Switched to a new branch 'jeffmccune-pdoc-34_fix_foo_error'
At this point the topic branch is a descendant of master, but we want it to It's possible that more changes have been merged into master since the pull
descend from `stable`. The committer rebases the change set onto `stable`. request was submitted. In this case it may be necessary to rebase the branch
that contains the changes:
$ git branch issue/stable/pdoc-34_fix_foo_error $ git rebase upstream/master
$ git rebase --onto stable master issue/stable/pdoc-34_fix_foo_error
First, rewinding head to replay your work on top of it...
Applying: (PDOC-34) Fix FooError that always bites users in 1.0.1
The `git rebase` command may be interpreted as, "First, check out the branch After the branch has been checked out and rebased, the committer should ensure that
named `bug/stable/fix_foo_error`, then take the changes that were previously the code review check list has been completed.
based on `master` and re-base them onto `stable`.
Now that we have a topic branch containing the change set based on the `stable` Now that we have a topic branch containing the change set based on the most recent
release branch, the committer merges in: `master` branch, the committer merges in:
$ git checkout stable
Switched to branch 'stable'
$ git merge --no-ff --log issue/stable/pdoc-34_fix_foo_error
Merge made by the 'recursive' strategy.
foo | 0
1 file changed, 0 insertions(+), 0 deletions(-)
create mode 100644 foo
Once merged into the first base branch, the committer merges the `stable`
branch into `master`, being careful to preserve the same commit identifiers.
$ git checkout master $ git checkout master
Switched to branch 'master' Switched to branch 'master'
$ git merge --no-ff --log stable $ git merge --no-ff --log jeffmccune-pdoc-34_fix_foo_error
Merge made by the 'recursive' strategy. Merge made by the 'recursive' strategy.
foo | 0 foo | 0
1 file changed, 0 insertions(+), 0 deletions(-) 1 file changed, 0 insertions(+), 0 deletions(-)
@ -231,13 +173,12 @@ preserve the usefulness of `git branch --contains`. If there are any merge
conflicts, they are to be resolved in the merge commit itself and not by conflicts, they are to be resolved in the merge commit itself and not by
re-writing (rebasing) the patches for one base branch, but not another. re-writing (rebasing) the patches for one base branch, but not another.
Once the change set has been merged into `stable` and into `master`, the Once the change set has been merged into `master`, the committer pushes.
committer pushes. Please note, the checklist should be complete at this point. Please note, the checklist should be complete at this point. It's helpful to make
It's helpful to make sure your local branches are up to date to avoid one of sure your local branches are up to date to avoid one of the branches failing to fast
the branches failing to fast forward while the other succeeds. Both the forward while the other succeeds.
`stable` and `master` branches are being pushed at the same time.
$ git push puppetlabs master:master stable:stable $ git push puppetlabs master:master
That's it! The committer then updates the pull request, updates the issue in That's it! The committer then updates the pull request, updates the issue in
our issue tracker, and keeps an eye on the [build our issue tracker, and keeps an eye on the [build