diff options
| -rw-r--r-- | CONTRIBUTING.md | 205 |
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/) |