[Pkg-puppet-devel] [facter] 96/352: (doc) Update COMMITTERS and CONTRIBUTING
Stig Sandbeck Mathisen
ssm at debian.org
Sun Apr 6 22:21:35 UTC 2014
This is an automated email from the git hooks/post-receive script.
ssm pushed a commit to branch master
in repository facter.
commit 9a2ff516d307f6aeda044e7c2dc65ae5b2f41b09
Author: Jeff McCune <jeff at puppetlabs.com>
Date: Wed Feb 13 14:53:00 2013 -0800
(doc) Update COMMITTERS and CONTRIBUTING
Without this patch the documentation describing our workflow and process
is out of date for Facter. This is a problem because community
contributors and people new to Puppet Labs have a more difficult time
learning how to submit contributions and merge contributions into the
codebase.
This patch addresses the problem by copying the COMMITTERS and
CONTRIBUTING documents from Puppet and customizing them specifically to
Facter.
[ci skip]
---
COMMITTERS.md | 185 +++++++++++++++++++++++++++++++++++
CONTRIBUTING.md | 294 ++++++++++++--------------------------------------------
2 files changed, 246 insertions(+), 233 deletions(-)
diff --git a/COMMITTERS.md b/COMMITTERS.md
new file mode 100644
index 0000000..6f81846
--- /dev/null
+++ b/COMMITTERS.md
@@ -0,0 +1,185 @@
+Committing changes to Facter
+====
+
+We would like to make it easier for community members to contribute to facter
+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
+branch, however, we maintain more than one active branch. As a result
+contributors should target their changes at the master branch. This makes the
+process of contributing a little easier for the contributor since they don't
+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).
+
+Therefore, it is the responsibility of the committer to re-base the change set
+on the appropriate branch which should receive the contribution.
+
+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
+a contribution on top of. This document also describes our branch management
+strategy, which is closely related to the decision of what branch to commit
+changes into.
+
+Terminology
+====
+
+Many of these terms have more than one meaning. For the purposes of this
+document, the following terms refer to specific things.
+
+**contributor** - A person who makes a change to facter and submits a change
+set in the form of a pull request.
+
+**change set** - A set of discrete patches which combined together form a
+contribution. A change set takes the form of Git commits and is submitted to
+facter in the form of a pull request.
+
+**committer** - A person responsible for reviewing a pull request and then
+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
+and will eventually be released using semantic version guidelines. The branch
+named master will always exist as a base branch. All other base branches will
+be associated with a specific released version of facter, e.g. 1.6.x and 1.7.x.
+
+Committer Guide
+====
+
+This section provides a guide to follow while committing change sets to facter
+base branches.
+
+How to decide what release(s) should be patched
+---
+
+This section provides a guide to help a committer decide the specific base
+branch that a change set should be merged into.
+
+The latest minor release of a major release is the only base branch that should
+be patched. Older minor releases in a major release do not get patched. Before
+the switch to [semantic versions](http://semver.org/) committers did not have
+to think about the difference between minor and major releases. Committing to
+the latest minor release of a major release is a policy intended to limit the
+number of active base branches that must be managed.
+
+Security patches are handled as a special case. Security patches may be
+applied to earlier minor releases of a major release.
+
+How to commit a change set to multiple base branches
+---
+
+A change set may apply to multiple releases. In this situation the change set
+needs to be committed to multiple base branches. This section provides a guide
+for how to merge patches across releases, e.g. 2.7 is patched, how should the
+changes be applied to 3.0?
+
+First, merge the change set into the lowest numbered base branch, e.g. 2.7.
+Next, merge the changed base branch up through all later base branches by using
+the `--no-ff --log` git merge options. We commonly refer to this as our "merge
+up process" because we merge in once, then merge up multiple times.
+
+When a new minor release branch is created (e.g. 3.1.x) then the previous one
+is deleted (e.g. 3.0.x). Any security or urgent fixes that might have to be
+applied to the older code line is done by creating an ad-hoc branch from the
+tag of the last patch release of the old minor line.
+
+Code review checklist
+---
+
+This section aims to provide a checklist of things to look for when reviewing a
+pull request and determining if the change set should be merged into a base
+branch:
+
+ * All tests pass
+ * Are there any platform gotchas? (Does a change make an assumption about
+ platform specific behavior that is incompatible with other platforms? e.g.
+ Windows paths vs. POSIX paths.)
+ * Is the change backwards compatible? (It should be)
+ * Are there YARD docs for API changes?
+ * Does the change set also require documentation changes? If so is the
+ documentation being kept up to date?
+ * Does the change set include clean code? (software code that is formatted
+ correctly and in an organized manner so that another coder can easily read
+ or modify it.) HINT: `git diff master --check`
+ * Does the change set conform to the contributing guide?
+
+
+Commit citizen guidelines:
+---
+
+This section aims to provide guidelines for being a good commit citizen by
+paying attention to our automated build tools.
+
+ * Don’t push on a broken build. (A broken build is defined as a failing job
+ in the [Facter](https://jenkins.puppetlabs.com/view/Facter/)
+ page.)
+ * Watch the build until your changes have gone through green
+ * Update the ticket status and target version. The target version field in
+ our issue tracker should be updated to be the next release of facter. For
+ example, if the most recent release of facter is 1.6.17 and you merge a
+ backwards compatible change set into master, then the target version should
+ be 1.7.0 in the issue tracker.)
+ * Ensure the pull request is closed (Hint: amend your merge commit to contain
+ the string `closes #123` where 123 is the pull request number.
+
+Example Procedure
+====
+
+This section helps a committer rebase a contribution onto an earlier base
+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
+fixes a bug reported against facter 1.7.1 which is the most recently released
+version of facter.
+
+In this example the committer should rebase the change set onto the 1.7.x
+branch since this is a bug rather than new functionality.
+
+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
+branch to track the remote branch.
+
+ $ hub checkout https://github.com/puppetlabs/facter/pull/1234
+ Branch jeffmccune-fix_foo_error set up to track remote branch fix_foo_error from jeffmccune.
+ Switched to a new branch 'jeffmccune-fix_foo_error'
+
+At this point the topic branch is a descendant of master, but we want it to
+descend from 1.7.x. The committer creates a new branch then re-bases the
+change set:
+
+ $ git branch bug/1.7.x/fix_foo_error
+ $ git rebase --onto 1.7.x master bug/1.7.x/fix_foo_error
+ First, rewinding head to replay your work on top of it...
+ Applying: (#23456) Fix FooError that always bites users in 1.7.1
+
+The `git rebase` command may be interpreted as, "First, check out the branch
+named `bug/1.7.x/fix_foo_error`, then take the changes that were previously
+based on `master` and re-base them onto `1.7.x`.
+
+Now that we have a topic branch containing the change set based on the correct
+release branch, the committer merges in:
+
+ $ git checkout 1.7.x
+ Switched to branch '1.7.x'
+ $ git merge --no-ff --log bug/1.7.x/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 up:
+
+ $ git checkout master
+ Switched to branch 'master'
+ $ git merge --no-ff --log 1.7.x
+ Merge made by the 'recursive' strategy.
+ foo | 0
+ 1 file changed, 0 insertions(+), 0 deletions(-)
+ create mode 100644 foo
+
+Once the change set has been merged "in and up." the committer pushes. (Note,
+the checklist should be complete at this point.) Note that both the 1.7.x and
+master branches are being pushed at the same time.
+
+ $ git push puppetlabs master:master 1.7.x:1.7.x
+
+That's it! The committer then updates the pull request, updates the issue in
+our issue tracker, and keeps an eye on the build status.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 9267016..44d68a5 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,237 +1,65 @@
-Checklist/Outline (The short version)
-=================================================
-
- * Getting Started:
- - Make sure you have a [Redmine account](http://projects.puppetlabs.com)
- - Submit a ticket for your issue, assuming one does not already exist.
- - Decide what to base your work off of
- * `1.6.x`: bug fixes only
- * `2.x`: new features that are not breaking changes
- * `master`: new features that are breaking changes
-
- * Making Changes:
- - Make sure you have a [GitHub account](https://github.com/signup/free)
- - Fork the repository on GitHub
- - Make commits of logical units.
- - Check for unnecessary whitespace with "git diff --check" before committing.
- - Make sure your commit messages are in the proper format
- - Make sure you have added the necessary tests for your changes
- - Run _all_ the tests to assure nothing else was accidentally broken
-
- * Submitting Changes:
- - Sign the [Contributor License Agreement](https://projects.puppetlabs.com/contributor_licenses/sign)
- - Push your changes to a topic branch in your fork of the repository.
- - Submit a pull request to the repository in the puppetlabs organization.
- - Update your Redmine ticket
-
-The long version
-================
-
- 0. Create a Redmine ticket for the change you'd like to make.
-
- It's very important that there be a Redmine ticket for the change
- you are making. Considering the number of contributions which are
- submitted, it is crucial that we know we can find the ticket on Redmine.
-
- Before making a ticket however, be sure that one does not already exist.
- You can do this by searching Redmine or by trying a Google search which
- includes `sites:projects.puppetlabs.com` in addition to some of the keywords
- related to your issue.
-
- If you do not find a ticket that that accurately describes the work
- you're going to be doing, go ahead and create one. But be sure to
- look for related tickets and add them to the 'related tickets' section.
-
- 1. Decide what to base your work on.
-
- In general, you should always base your work on the oldest
- branch that your change is relevant to, and it will be
- eventually merged up. Currently, branches will be merged up as
- follows:
- 1.6.x => 2.x => master
-
- Currently, this is how you should decide where to target your changes:
-
- A bug fix should be based off the the earliest place where it is
- relevant. If it first appears in `1.6.x`, then it should be
- targeted here and eventually merged up to `2.x` and master.
-
- New features which are _backwards compatible_ should be targeted
- at the next release, which currently is `2.x`.
-
- New features that are _breaking changes_ should be targeted at
- `master`.
-
- Part of deciding what to what your work should be based off of includes naming
- your topic branch to reflect this. Your branch name should have the following
- format:
- `ticket/target_branch/ticket_number_short_description_of_issuee`
-
- For example, if you are fixing a bug relating to a hostname problem on aix,
- which has Redmine ticket number 12345, then your branch should be named:
- `ticket/2.x/12345_fix_hostname_on_aix`
-
- There is a good chance that if you submit a pull request _from_ master _to_ master,
- Puppet Labs developers will suspect that you're not sure about the process. This is
- why clear naming of branches and basing your work off the right place will be
- extremely helpful in ensuring that your submission is reviewed and merged. Often times
- if your change is targeted at the wrong place, we will bounce it back to you and wait
- to review it until it has been retargeted.
-
- 2. Make separate commits for logically separate changes.
-
- Please break your commits down into logically consistent units
- which include new or changed tests relevent to the rest of the
- change. The goal of doing this is to make the diff easier to
- read for whoever is reviewing your code. In general, the easier
- your diff is to read, the more likely someone will be happy to
- review it and get it into the code base.
-
- If you're going to refactor a piece of code, please do so as a
- separate commit from your feature or bug fix changes.
-
- It's crucial that your changes include tests to make
- sure the bug isn't re-introduced, and that the feature isn't
- accidentally broken.
-
- Describe the technical detail of the change(s). If your
- description starts to get too long, that's a good sign that you
- probably need to split up your commit into more finely grained
- pieces.
-
- Commits which plainly describe the the things which help
- reviewers check the patch and future developers understand the
- code are much more likely to be merged in with a minimum of
- bike-shedding or requested changes. Ideally, the commit message
- would include information, and be in a form suitable for
- inclusion in the release notes for the version of Facter that
- includes them.
-
- Please also check that you are not introducing any trailing
- whitespaces or other "whitespace errors". You can do this by
- running "git diff --check" on your changes before you commit.
-
- When writing commit messages, please be sure they meet
- [these standards](https://github.com/erlang/otp/wiki/Writing-good-commit-messages), and please include the ticket number in your
- short summary. It should look something like this: `(#12345) Fix this issue in Facter`
-
- 3. Sign the Contributor License Agreement
-
- Before we can accept your changes, we do need a signed Puppet
- Labs Contributor License Agreement (CLA).
-
- You can access the CLA via the
- [Contributor License Agreement link](https://projects.puppetlabs.com/contributor_licenses/sign)
- in the top menu bar of our Redmine instance. Once you've signed
- the CLA, a badge will show up next to your name on the
- [Puppet Project Overview Page](http://projects.puppetlabs.com/projects/puppet?jump=welcome),
- and your name will be listed under "Contributor License Signers"
- section.
-
- If you have any questions about the CLA, please feel free to
- contact Puppet Labs via email at cla-submissions at puppetlabs.com.
-
- 4. Sending your patches
-
- To submit your changes via a GitHub pull request, you must
- have them on a topic branch, instead of directly on "master"
- or one of the release, or RC branches. It makes things much easier
- to keep track of, especially if you decide to work on another thing
- before your first change is merged in.
-
- GitHub has some pretty good
- [general documentation](http://help.github.com/) on using
- their site. They also have documentation on
- [creating pull requests](http://help.github.com/send-pull-requests/).
-
- In general, after pushing your topic branch up to your
- repository on GitHub, you'll switch to the branch in the
- GitHub UI and click "Pull Request" towards the top of the page
- in order to open a pull request.
-
- You'll want to make sure that you have the appropriate
- destination branch in the repository under the puppetlabs
- organization. This should be the same branch that you based
- your changes off of.
-
- 5. Update the related Redmine ticket.
-
- You should update the Redmine ticket associated
- with the change you submitted to include the location of your branch
- on the `branch` field of the ticket, and change the status to
- "In Topic Branch Pending Review", along with any other commentary
- you may wish to make.
-
-How to track the status of your change after it's been submitted
-================================================================
-
-Shortly after opening a pull request, there should be an automatic
-email sent via GitHub. This notification is used to let the Puppet
-development community know about your requested change to give them a
-chance to review, test, and comment on the change(s).
-
-We do our best to comment on or merge submitted changes within a about week.
-However, if there hasn't been any commentary on the pull request or
-mailed patches, and it hasn't been merged in after a week, then feel
-free to ask for an update by replying on the mailing list to the
-automatic notification or mailed patches. It probably wasn't
-intentional, and probably just slipped through the cracks.
-
-Additional Resources
-====================
-
-* [Getting additional help](http://projects.puppetlabs.com/projects/puppet/wiki/Getting_Help)
-
-* [Writing tests](http://projects.puppetlabs.com/projects/puppet/wiki/Development_Writing_Tests)
-
+# How to contribute
+
+Third-party patches are essential for keeping facter great. We simply can't
+access the huge number of platforms and myriad configurations for running
+facter. We want to keep it as easy as possible to contribute changes that
+get things working in your environment. There are a few guidelines that we
+need contributors to follow so that we can have a chance of keeping on
+top of things.
+
+## Getting Started
+
+* Make sure you have a [Redmine account](http://projects.puppetlabs.com)
+* Make sure you have a [GitHub account](https://github.com/signup/free)
+* Submit a ticket for your issue, assuming one does not already exist.
+ * Clearly describe the issue including steps to reproduce when it is a bug.
+ * Make sure you fill in the earliest version that you know has the issue.
+* Fork the repository on GitHub
+
+## Making Changes
+
+* Create a topic branch from where you want to base your work.
+ * This is usually the master branch.
+ * Only target release branches if you are certain your fix must be on that
+ branch.
+ * To quickly create a topic branch based on master; `git branch
+ fix/master/my_contribution master` then checkout the new branch with `git
+ checkout fix/master/my_contribution`. Please avoid working directly on the
+ `master` branch.
+* Make commits of logical units.
+* Check for unnecessary whitespace with `git diff --check` before committing.
+* Make sure your commit messages are in the proper format.
+
+````
+ (#99999) Make the example in CONTRIBUTING imperative and concrete
+
+ Without this patch applied the example commit message in the CONTRIBUTING
+ document is not a concrete example. This is a problem because the
+ contributor is left to imagine what the commit message should look like
+ based on a description rather than an example. This patch fixes the
+ problem by making the example concrete and imperative.
+
+ The first line is a real life imperative statement with a ticket number
+ from our issue tracker. The body describes the behavior without the patch,
+ why this is a problem, and how the patch fixes the problem when applied.
+````
+
+* Make sure you have added the necessary tests for your changes.
+* Run _all_ the tests to assure nothing else was accidentally broken.
+
+## Submitting Changes
+
+* Sign the [Contributor License Agreement](https://projects.puppetlabs.com/contributor_licenses/sign).
+* Push your changes to a topic branch in your fork of the repository.
+* Submit a pull request to the repository in the puppetlabs organization.
+* Update your Redmine ticket to mark that you have submitted code and are ready for it to be reviewed.
+ * Include a link to the pull request in the ticket
+
+# Additional Resources
+
+* [More information on contributing](http://links.puppetlabs.com/contribute-to-puppet)
* [Bug tracker (Redmine)](http://projects.puppetlabs.com)
-
* [Contributor License Agreement](https://projects.puppetlabs.com/contributor_licenses/sign)
-
* [General GitHub documentation](http://help.github.com/)
-
* [GitHub pull request documentation](http://help.github.com/send-pull-requests/)
-
-If you have commit access to the repository
-===========================================
-
-Even if you have commit access to the repository, you'll still need to
-go through the process above, and have someone else review and merge
-in your changes. The rule is that all changes must be reviewed by a
-developer on the project (that didn't write the code) to ensure that
-all changes go through a code review process.
-
-Having someone other than the author of the topic branch recorded as
-performing the merge is the record that they performed the code
-review.
-
- * Merging topic branches
-
- When merging code from a topic branch into the integration branch
- (Ex: master, 2.7.x, 1.6.x, etc.), there should always be a merge
- commit. You can accomplish this by always providing the `--no-ff`
- flag to `git merge`.
-
- git merge --no-ff --log tickets/master/1234-fix-something-broken
-
- The reason for always forcing this merge commit is that it
- provides a consistent way to look up what changes & commits were
- in a topic branch, whether that topic branch had one, or 500
- commits. For example, if the merge commit had an abbreviated
- SHA-1 of `coffeebad`, then you could use the following `git log`
- invocation to show you which commits it brought in:
-
- git log coffeebad^1..coffeebad^2
-
- The following would show you which changes were made on the topic
- branch:
-
- git diff coffeebad^1...coffeebad^2
-
- Because we _always_ merge the topic branch into the integration
- branch the first parent (`^1`) of a merge commit will be the most
- recent commit on the integration branch from just before we merged
- in the topic, and the second parent (`^2`) will always be the most
- recent commit that was made in the topic branch. This also serves
- as the record of who performed the code review, as mentioned
- above.
+* #puppet-dev IRC channel on freenode.org
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-puppet/facter.git
More information about the Pkg-puppet-devel
mailing list