summaryrefslogtreecommitdiff
path: root/CONTRIBUTING.md
diff options
context:
space:
mode:
authorBryan McLellan <btm@opscode.com>2012-09-18 09:15:06 -0700
committerBryan McLellan <btm@opscode.com>2012-09-18 09:15:06 -0700
commiteb807e80d0d423dc2e3339343c19dee31b65048a (patch)
tree26521a47ab5730469f96c618256b7fe959dbf0d2 /CONTRIBUTING.md
parent441f48233a68f3bcd21a8f774af62100b3322ca8 (diff)
downloadchef-eb807e80d0d423dc2e3339343c19dee31b65048a.tar.gz
New CONTRIBUTING.md file
Initial brain dump of information relevant to contributing
Diffstat (limited to 'CONTRIBUTING.md')
-rw-r--r--CONTRIBUTING.md152
1 files changed, 152 insertions, 0 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000000..6da0defc81
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,152 @@
+# Contributing to Chef
+
+We are glad you want to contribute to Chef! The first step is the desire to improve the project.
+
+You can find the answers to additional frequently asked questions [on the wiki](http://wiki.opscode.com/display/chef/How+to+Contribute).
+
+## Quick-contribute
+
+* 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
+
+We regularly review contributions and will get back to you if we have any suggestions or concerns.
+
+## The Apache License and the CLA/CCLA
+
+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.
+
+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, Opscode 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.
+
+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.
+
+## Ticket Tracker (JIRA)
+
+The [ticket tracker](http://tickets.opscode.com) is the most important documentation for the code base. It provides significant historical information,
+such as:
+
+* Which release a bug fix is included in
+* Discussion regarding the design and merits of features
+* Error output to aid in finding similar bugs
+
+Each ticket should aim to fix one bug or add one feature.
+
+## Using git
+
+You can get a quick copy of the chef repository by running `git clone git://github.com/opscode/chef.git`.
+
+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.
+
+### Branches and Commits
+
+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.
+
+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.
+
+ CHEF-3435: Create deploy dirs before calling scm_provider
+
+ 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.
+
+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.
+
+### Github and Pull Requests
+
+All of Opscode'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.
+
+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.
+
+### More information
+
+Additional help with git is available on the [Working with Git](http://wiki.opscode.com/display/chef/Working+with+Git) wiki page.
+
+## Functional and Unit Tests
+
+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.
+
+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.
+
+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
+
+Opscode 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 will tag the _Code Reviewed_ field with _Reviewed_.
+
+Depending on the project, these tickets are then merged within a week or two, depending on the current release cycle.
+
+## Release Cycle
+
+The versioning for the Chef project is X.Y.Z.
+
+* 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 and have historically been once a year. Minor releases for Chef average every two months and patch releases come as needed.
+
+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.
+
+Once the official release is made, the release notes are available on the [Opscode blog](http://www.opscode.com/blog).
+
+## Working with the community
+
+These resources will help you learn more about Chef and connect to other members of the Chef community:
+
+* [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)
+* Opscode Chef [product page](http://www.opscode.com/chef)
+