summaryrefslogtreecommitdiff
path: root/CONTRIBUTING.md
diff options
context:
space:
mode:
Diffstat (limited to 'CONTRIBUTING.md')
-rw-r--r--CONTRIBUTING.md205
1 files changed, 105 insertions, 100 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 9d9839fd5c..7302945425 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,155 +1,160 @@
# 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. Report an issue or make a feature request [here](#issues)
+2. Contribute 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 an easy 3 step process that utilizes **Github Issues**:
-## The Apache License and the CLA/CCLA
+1. Spare two minutes to sign our
+ [Contributor License Agreement (CLA)](https://secure.echosign.com/public/hostedForm?formid=PJIF5694K6L)
+ or [Corporate CLA](https://secure.echosign.com/public/hostedForm?formid=PIE6C7AX856) online.
+2. Create a Github Pull Request.
+3. Do [Code Review](#cr) with **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 thrive to ensure high quality throughout 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 future regressions we require all the
+ code in Chef to have at least unit test coverage.
+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.
-
-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.
+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.
-## Ticket Tracker (JIRA)
+### <a name="cr"></a> Chef Code Review Process
-The [ticket tracker](http://tickets.opscode.com) is the most important documentation for the code base. It provides significant historical information,
-such as:
+Chef Code Review Process completely happens on Github. See
+ [this article](https://help.github.com/articles/using-pull-requests) if you're not
+ familiar with Github Pull Requests.
-* Which release a bug fix is included in
-* Discussion regarding the design and merits of features
-* Error output to aid in finding similar bugs
+Once you a pull request, **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:
-Each ticket should aim to fix one bug or add one feature.
+1. 2 thumbs-ups are required from **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. **In at most 2 weeks** your patch will be merged into `master` including necessary documentation updates
+ and you will be included in `CHANGELOG.md`.
-## Using git
+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).
-You can get a quick copy of the chef repository by running `git clone git://github.com/opscode/chef.git`.
+### 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.
-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 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.
-### Branches and Commits
+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.
-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.
+To make a good faith effort to ensure these criteria are met, Chef requires a CLA
+ or a Corporate CLA for contributions. This is not related to copyrights and it
+ helps us avoid continually checking with our lawyers for your patches.
-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.
+It only takes a few minutes to complete a CLA, and you retain the copyright to your contribution.
- CHEF-3435: Create deploy dirs before calling scm_provider
+You can complete our 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.
- 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.
+### Chef Obvious Fix Policy
-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.
+**TODO: Include some information here.**
-### Github and Pull Requests
+## <a name="issues"></a> Chef Issue Tracking
-All of Chef's open source projects are available on [Github](http://www.github.com/opscode).
+Chef Issue Tracking is completely handled on Github Issues.
-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.
+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/).
-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.
+Otherwise you can file your issue in [chef project](https://github.com/opscode/chef/issues)
+ and we will make sure it is propagated correctly.
-### More information
+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.
-Additional help with git is available on the [Working with Git](http://wiki.opscode.com/display/chef/Working+with+Git) wiki page.
+<a name="issuetemplate"></a>
+```
+### Version:
+[Version of the project installed]
-## Functional and Unit Tests
+### Environment: [Details about the environment such as the Operating System, cookbook details, etc...]
-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.
+### Scenario:
+[What you are trying to achieve and you can't?]
-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.
-If any don't pass, investigate them before submitting your patch.
-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.
+### Repro Steps:
+[If you are filing an issue what are the things we need to do in order to repro your problem?]
-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
+### Expected Result:
+[What are you expecting to happen as the consequence of above repro steps?]
-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_.
+### Actual Result:
+[What actually happens after the repro 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_.
+## <a name="release"></a> Chef Release Cycles
-Please see the [Code Review](http://wiki.opscode.com/display/chef/Code+Review) page on the wiki for additional information.
+Our primary shipping vehicle is operating system specific packages that includes
+ all the requirements of Chef.
-## Release Cycle
+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.
-The versioning for the Chef project is X.Y.Z.
+Our version number 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.
-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.
+We do a `Minor` release approximately every 3 months and `Patch` releases on a when-needed
+ basis for regressions, significant bugs and security issues.
-Once the official release is made, the release notes are available on the [Chef blog](http://www.getchef.com/blog).
+Announcements of releases are available on [Chef Blog](http://www.getchef.com/blog) when they are
+ available.
-## 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 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 and \#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/)
+* [LearnChef](https://learnchef.opscode.com/)
+* [Chef Inc](http://www.getchef.com/)