facter 1.7.6 → 2.0.1.rc1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 3d91c7a71d4cc61bb1f50ab005c54eb09b938691
+  data.tar.gz: 624a61aa2493e96ffa71b8a0b9a0c258eec84d49
+SHA512:
+  metadata.gz: 0364c8c7f7238493331a2e33ba53e6104dcba79a1c8f63f83b76714c86bc67a82e5ac5bfe651f767ee553d96366be8684beb8e4055de43d6e661a5f3e20878ba
+  data.tar.gz: 0261cc7fe89129ccde61c5b42eaac43f74e3532c5f761d0ebb88f0305b4e838d0a069dba636c39651a34e7d7f5442128024f1ef6b04ae2cce91c5dfeee7d65ab

data/COMMITTERS.md

@@ -0,0 +1,194 @@
+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 facter-2 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.
+
+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 --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 2.0.1 and you merge a
+   backwards compatible change set into facter-2, then the target version should
+   be 2.1.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 facter-2.  The change set
+fixes a bug reported against facter 2.0.1 which is the most recently released
+version of facter.
+
+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
+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 facter-2, but we want it to
+descend from stable.  The committer creates a new branch then re-bases the
+change set:
+
+    $ git branch bug/stable/fix_foo_error
+    $ git rebase --onto stable master bug/stable/fix_foo_error
+    First, rewinding head to replay your work on top of it...
+    Applying: (#23456) Fix FooError that always bites users in 2.0.1
+
+The `git rebase` command may be interpreted as, "First, check out the branch
+named `bug/stable/fix_foo_error`, then take the changes that were previously
+based on `facter-2` and re-base them onto `stable`.
+
+Now that we have a topic branch containing the change set based on the correct
+release branch, the committer merges in:
+
+    $ git checkout stable
+    Switched to branch 'stable'
+    $ git merge --no-ff --log bug/stable/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 to facter-2:
+
+    $ git checkout facter-2
+    Switched to branch 'facter-2'
+    $ git merge --no-ff --log stable
+    Merge made by the 'recursive' strategy.
+     foo | 0
+     1 file changed, 0 insertions(+), 0 deletions(-)
+     create mode 100644 foo
+
+And then merges up to master:
+
+    $ git checkout master
+    Switched to branch 'master'
+    $ git merge --no-ff --log stable
+    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 the stable,
+facter-2 and master branches are being pushed at the same time.
+
+    $ git push puppetlabs master:master facter-2:facter-2 stable:stable
+
+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.

data/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@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)
-
-* [Bug tracker (Redmine)](http://projects.puppetlabs.com)
-
-* [Contributor License Agreement](https://projects.puppetlabs.com/contributor_licenses/sign)
-
+# 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 [Jira account](http://tickets.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 facter-2 branch.
+  * Only target release branches if you are certain your fix must be on that
+    branch.
+  * To quickly create a topic branch based on facter-2; `git branch
+    fix/facter-2/my_contribution facter-2` then checkout the new branch with `git
+    checkout fix/facter-2/my_contribution`.  Please avoid working directly on the
+    `facter-2` 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](http://links.puppetlabs.com/cla).
+* 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 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 (Jira)](http://tickets.puppetlabs.com)
+* [Contributor License Agreement](http://links.puppetlabs.com/cla)
 * [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