Merge pull request #1463 from opscode/sersut/contribution-info

Update CONTRIBUTING.md per new Github process.

1 files changed, 140 insertions, 99 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 9d9839fd5c..510e4e19d8 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,155 +1,196 @@
 # Contributing to Chef
 
-We are glad you want to contribute to Chef! The first step is the desire to improve the project.
+We are glad you want to contribute to Chef!
 
-You can find the answers to additional frequently asked questions [on the wiki](http://wiki.opscode.com/display/chef/How+to+Contribute).
+We utilize **Github Issues** for issue tracking and contributions. You can contribute in two ways:
 
-## Quick-contribute
+1. Reporting an issue or making a feature request [here](#issues).
+2. Adding features or fixing bugs yourself and contributing your code to Chef.
 
-*   Create an account on our [bug tracker](http://tickets.opscode.com)
-*   Sign our contributor agreement (CLA) [
-online](https://secure.echosign.com/public/hostedForm?formid=PJIF5694K6L)
-    (keep reading if you're contributing on behalf of your employer)
-* Create a ticket for your change on the [bug tracker](http://tickets.opscode.com)
-* Link to your patch as a rebased git branch or pull request from the ticket
-* Resolve the ticket as fixed
+## Contribution Process
 
-We regularly review contributions and will get back to you if we have any suggestions or concerns.
+We have a 3 step process that utilizes **Github Issues**:
 
-## The Apache License and the CLA/CCLA
+1. Sign our
+  [Individual Contributor License Agreement (CLA)](https://secure.echosign.com/public/hostedForm?formid=PJIF5694K6L)
+  or [Corporate CLA](https://secure.echosign.com/public/hostedForm?formid=PIE6C7AX856) online once.
+2. Create a Github Pull Request.
+3. Do [Code Review](#cr) with the **Chef Engineering Team** or **Chef Core Committers** on the pull request.
 
-Licensing is very important to open source projects, it helps ensure the software continues to be available under the terms that the author desired.
-Chef uses the Apache 2.0 license to strike a balance between open contribution and allowing you to use the software however you would like to.
+### <a name="pulls"></a> Chef Pull Requests
 
-The license tells you what rights you have that are provided by the copyright holder. It is important that the contributor fully understands what rights
-they are licensing and agrees to them. Sometimes the copyright holder isn't the contributor, most often when the contributor is doing work for a company.
+Chef is built to last. We strive to ensure high quality throughout the Chef experience. In order to ensure
+  this, we require a couple of things for all pull requests to Chef:
 
-To make a good faith effort to ensure these criteria are met, Chef requires a Contributor License Agreement (CLA) or a Corporate Contributor License
-Agreement (CCLA) for all contributions. This is without exception due to some matters not being related to copyright and to avoid having to continually
-check with our lawyers about small patches.
+1. **Tests:** To ensure high quality code and protect against future regressions, we require all the
+  code in Chef to have at least unit test coverage. See the [spec/unit](https://github.com/opscode/chef/tree/master/spec/unit)
+  directory for the existing tests and use ```bundle exec rake spec``` to run them.
+2. **Green Travis Run:** We use [Travis CI](https://travis-ci.org/) in order to run our tests
+  continuously on all the pull requests. We require the Travis runs to succeed on every pull
+  request before being merged.
 
-It only takes a few minutes to complete a CLA, and you retain the copyright to your contribution.
+In addition to this it would be nice to include the description of the problem you are solving
+  with your change. You can use [Chef Issue Template](#issuetemplate) in the description section
+  of the pull request.
+
+### <a name="cr"></a> Chef Code Review Process
+
+The Chef Code Review process happens on Github pull requests. See
+  [this article](https://help.github.com/articles/using-pull-requests) if you're not
+  familiar with Github Pull Requests.
 
-You can complete our contributor agreement (CLA) [
-online](https://secure.echosign.com/public/hostedForm?formid=PJIF5694K6L).  If you're contributing on behalf of your employer, have
-your employer fill out our [Corporate CLA](https://secure.echosign.com/public/hostedForm?formid=PIE6C7AX856) instead.
+Once you a pull request, the **Chef Engineering Team** or **Chef Core Committers** will review your code
+  and respond to you with any feedback they might have. The process at this point is as follows:
 
-## Ticket Tracker (JIRA)
+1. 2 thumbs-ups are required from the **Chef Engineering Team** or **Chef Core Committers** for all merges.
+2. When ready, your pull request will be tagged with label `Ready For Merge`.
+3. Your patch will be merged into `master` including necessary documentation updates
+  and you will be included in `CHANGELOG.md`. Our goal is to have patches merged in 2 weeks
+  after they are marked to be merged.
 
-The [ticket tracker](http://tickets.opscode.com) is the most important documentation for the code base. It provides significant historical information,
-such as:
+If you would like to learn about when your code will be available in a release of Chef, read more about
+  [Chef Release Process](#release).
 
-* Which release a bug fix is included in
-* Discussion regarding the design and merits of features
-* Error output to aid in finding similar bugs
+### Contributor License Agreement (CLA)
+Licensing is very important to open source projects. It helps ensure the
+  software continues to be available under the terms that the author desired.
 
-Each ticket should aim to fix one bug or add one feature.
+Chef uses [the Apache 2.0 license](https://github.com/opscode/chef/blob/master/LICENSE)
+  to strike a balance between open contribution and allowing you to use the
+  software however you would like to.
 
-## Using git
+The license tells you what rights you have that are provided by the copyright holder.
+  It is important that the contributor fully understands what rights they are
+  licensing and agrees to them. Sometimes the copyright holder isn't the contributor,
+  most often when the contributor is doing work for a company.
+
+To make a good faith effort to ensure these criteria are met, Chef requires an Individual CLA
+  or a Corporate CLA for contributions. This agreement helps ensure you are aware of the
+  terms of the license you are contributing your copyrighted works under, which helps to
+  prevent the inclusion of works in the projects that the contributor does not hold the rights
+  to share.
+
+It only takes a few minutes to complete a CLA, and you retain the copyright to your contribution.
 
-You can get a quick copy of the chef repository by running `git clone git://github.com/opscode/chef.git`.
+You can complete our
+  [Individual CLA](https://secure.echosign.com/public/hostedForm?formid=PJIF5694K6L) online.
+  If you're contributing on behalf of your employer and they retain the copyright for your works,
+  have your employer fill out our
+  [Corporate CLA](https://secure.echosign.com/public/hostedForm?formid=PIE6C7AX856) instead.
 
-For collaboration purposes, it is best if you create a Github account and fork the repository to your own account.
-Once you do this you will be able to push your changes to your Github repository for others to see and use.
+### Chef Obvious Fix Policy
 
-### Branches and Commits
+Small contributions such as fixing spelling errors, where the content is small enough
+  to not be considered intellectual property, can be submitted by a contributor as a patch,
+  without a CLA.
 
-You should submit your patch as a git branch named after the ticket, such as CHEF-1337.
-This is called a _topic branch_ and allows users to associate a branch of code with the ticket.
+As a rule of thumb, changes are obvious fixes if they do not introduce any new functionality
+  or creative thinking. As long as the change does not affect functionality, some likely
+  examples include the following:
 
-It is a best practice to have your commit message have a _summary line_ that includes the ticket number,
-followed by an empty line and then a brief description of the commit. This also helps other contributors
-understand the purpose of changes to the code.
+* Spelling / grammar fixes
+* Typo correction, white space and formatting changes
+* Comment clean up
+* Bug fixes that change default return values or error codes stored in constants
+* Adding logging messages or debugging output
+* Changes to ‘metadata’ files like Gemfile, .gitignore, build scripts, etc.
+* Moving source files from one directory or package to another
 
-    CHEF-3435: Create deploy dirs before calling scm_provider
+**Whenever you invoke the “obvious fix” rule, please say so in your commit message:**
 
-    The SCM providers have an assertation that requires the deploy directory to
-    exist. The deploy provider will create missing directories, we don't converge
-    the actions before we call run_action against the SCM provider, so it is not
-    yet created. This ensures we run any converge actions waiting before we call
-    the SCM provider.
+```
+------------------------------------------------------------------------
+commit 370adb3f82d55d912b0cf9c1d1e99b132a8ed3b5
+Author: danielsdeleo <dan@opscode.com>
+Date:   Wed Sep 18 11:44:40 2013 -0700
 
-Remember that not all users use Chef in the same way or on the same operating systems as you, so it is
-helpful to be clear about your use case and change so they can understand it even when it doesn't apply to them.
+  Fix typo in config file docs.
 
-### Github and Pull Requests
+  Obvious fix.
 
-All of Chef's open source projects are available on [Github](http://www.github.com/opscode).
+------------------------------------------------------------------------
+```
 
-We don't require you to use Github, and we will even take patch diffs attached to tickets on the tracker.
-However Github has a lot of convenient features, such as being able to see a diff of changes between a
-pull request and the main repository quickly without downloading the branch.
+## <a name="issues"></a> Chef Issue Tracking
 
-If you do choose to use a pull request, please provide a link to the pull request from the ticket __and__
-a link to the ticket from the pull request. Because pull requests only have two states, open and closed,
-we can't easily filter pull requests that are waiting for a reply from the author for various reasons.
+Chef Issue Tracking is handled using Github Issues.
 
-### More information
+If you are familiar with Chef and know the component that is causing you a problem or if you
+  have a feature request on a specific component you can file an issue in the corresponding
+  Github project. All of our Open Source Software can be found in our
+  [Github organization](https://github.com/opscode/).
 
-Additional help with git is available on the [Working with Git](http://wiki.opscode.com/display/chef/Working+with+Git) wiki page.
+Otherwise you can file your issue in the [Chef project](https://github.com/opscode/chef/issues)
+  and we will make sure it gets filed against the appropriate project.
 
-## Functional and Unit Tests
+In order to decrease the back and forth an issues and help us get to the bottom of them quickly
+  we use below issue template. You can copy paste this code into the issue you are opening and
+  edit it accordingly.
 
-There are rspec unit tests in the 'spec' directory. If you don't have rspec already installed, you can use the 'bundler'
-gem to help you get the necessary prerequisites by running `sudo gem install bundler` and then `bundle install` from
-the chef respository. You can run the chef client spec tests by running `rspec spec/*` or `rake spec` from the chef
-directory of the chef repository.
+<a name="issuetemplate"></a>
+```
+### Version:
+[Version of the project installed]
 
-These tests should pass successfully on Ruby 1.8 and 1.9 on all of the platforms that Chef runs on. It is good to run the tests
-once on your system before you get started to ensure they all pass so you have a valid baseline. After you write your patch,
-run the tests again to see if they all pass.
+### Environment: [Details about the environment such as the Operating System, cookbook details, etc...]
 
-If any don't pass, investigate them before submitting your patch.
+### Scenario:
+[What you are trying to achieve and you can't?]
 
-These tests don't modify your system, and sometimes tests fail because a command that would be run has changed because of your
-patch. This should be a simple fix. Other times the failure can show you that an important feature no longer works because of
-your change.
 
-Any new feature should have unit tests included with the patch with good code coverage to help protect it from future changes.
-Similarly, patches that fix a bug or regression should have a _regression test_. Simply put, this is a test that would fail
-without your patch but passes with it. The goal is to ensure this bug doesn't regress in the future. Consider a regular
-expression that doesn't match a certain pattern that it should, so you provide a patch and a test to ensure that the part
-of the code that uses this regular expression works as expected. Later another contributor may modify this regular expression
-in a way that breaks your use cases. The test you wrote will fail, signalling to them to research your ticket and use case
-and accounting for it.
 
-## Code Review
+### Steps to Reproduce:
+[If you are filing an issue what are the things we need to do in order to repro your problem?]
 
-Chef regularly reviews code contributions and provides suggestions for improvement in the code itself or the implementation.
 
-We find contributions by searching the ticket tracker for _resolved_ tickets with a status of _fixed_. If we have feedback we will
-reopen the ticket and you should resolve it again when you've made the changes or have a response to our feedback. When we believe
-the patch is ready to be merged, we update the status to _Fix Reviewed_.
+### Expected Result:
+[What are you expecting to happen as the consequence of above reproduction steps?]
 
-Depending on the project, these tickets are then merged within a week or two, depending on the current release cycle. At this
-point the ticket status will be updated to _Fix Committed_ or _Closed_.
 
-Please see the [Code Review](http://wiki.opscode.com/display/chef/Code+Review) page on the wiki for additional information.
+### Actual Result:
+[What actually happens after the reproduction steps?]
+```
 
-## Release Cycle
+## <a name="release"></a> Chef Release Cycles
 
-The versioning for the Chef project is X.Y.Z.
+Our primary shipping vehicle is operating system specific packages that includes
+  all the requirements of Chef. We call these [Omnibus packages](https://github.com/opscode/omnibus-ruby)
+
+We also release our software as gems to [Rubygems](http://rubygems.org/) but we strongly
+  recommend using Chef packages since they are the only combination of native libraries &
+  gems required by Chef that we test throughly.
+
+Our version numbering closely follows [Semantic Versioning](http://semver.org/) standard. Our
+  standard version numbers look like X.Y.Z which mean:
 
 * X is a major release, which may not be fully compatible with prior major releases
 * Y is a minor release, which adds both new features and bug fixes
 * Z is a patch release, which adds just bug fixes
 
-Major releases have historically been once a year. Minor releases for Chef average every three months and patch releases come as needed.
+We frequently make `alpha` and `beta` releases with version numbers that look like
+  `X.Y.Z.alpha.0` or `X.Y.Z.beta.1`. These releases are still well tested but not as
+  throughly as **Minor** or **Patch** releases.
+
+We do a `Minor` release approximately every 3 months and `Patch` releases on a when-needed
+  basis for regressions, significant bugs, and security issues.
 
-There are usually beta releases and release candidates (RC) of major and minor releases announced on
-the [chef-dev mailing list](http://lists.opscode.com/sympa/info/chef-dev). Once an RC is released, we wait at least three
-days to allow for testing for regressions before the final release. If a blocking regression is found then another RC is made containing
-the fix and the timer is reset.
+Announcements of releases are available on [Chef Blog](http://www.getchef.com/blog) when they are
+  available.
 
-Once the official release is made, the release notes are available on the [Chef blog](http://www.getchef.com/blog).
+  **TODO**: Can I sign up for a mailing list to get notification of releases?
 
-## Working with the community
+## Chef Community
 
-These resources will help you learn more about Chef and connect to other members of the Chef community:
+Chef is made possible by a strong community of developers and system administrators. If you have
+  any questions or if you would like to get involved in the Chef community you can check out:
 
 * [chef](http://lists.opscode.com/sympa/info/chef) and [chef-dev](http://lists.opscode.com/sympa/info/chef-dev) mailing lists
-* #chef and #chef-hacking IRC channels on irc.freenode.net
-* [Community Cookbook site](http://community.opscode.com)
-* [Chef wiki](http://wiki.opscode.com/display/chef)
-* Chef [product page](http://www.getchef.com/chef)
+* [\#chef](https://botbot.me/freenode/chef) and [\#chef-hacking](https://botbot.me/freenode/chef-hacking) IRC channels on irc.freenode.net
+
+Also here are some additional pointers to some awesome Chef content:
+
+**TODO**: Any blogs of community folks that we would like to put in here?
 
+* [Chef Docs](http://docs.opscode.com/)
+* [Learn Chef](https://learnchef.opscode.com/)
+* [Chef Inc](http://www.getchef.com/)