Permalink
Browse files

Add a CONTRIBUTING document

Copied from Chef, updated a bit for Ohai and recent changes
  • Loading branch information...
1 parent 71c4778 commit 6f00cca7b5356a6ebce9588453c7259605e3e7e3 @btm btm committed Oct 24, 2013
Showing with 153 additions and 0 deletions.
  1. +153 −0 CONTRIBUTING.md
View
@@ -0,0 +1,153 @@
+# Contributing to Ohai
+
+We are glad you want to contribute to Ohai! The first step is the desire to improve the project.
+
+Answers to many questions about contributing can also be found on the [community contributions](http://docs.opscode.com/community_contributions.html) page.
+
+## 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 'fix provided'
+
+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.
+Ohai 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 ohai repository by running `git clone git://github.com/opscode/ohai.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 OHAI-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.
+
+ OHAI-489: Use module functions to avoid method name conflict
+
+ Fixes conflict over method names `fetch_metadata` and `http_client` in
+ the Ohai::System instance by modifying the GCE mixin to define these as
+ module functions and changing the plugin to call them as module
+ functions.
+
+Remember that not all users use Ohai 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 ohai respository. You can run the ohai client spec tests by running `rspec spec/*` or `rake spec` from the ohai
+directory of the ohai repository.
+
+These tests should pass successfully on Ruby 1.8 and 1.9 on all of the platforms that Ohai 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 _Fix Provided_tickets. 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_.
+
+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.
+
+## Release Cycle
+
+The versioning for the Ohai 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 Ohai 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 Ohai 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)
+

0 comments on commit 6f00cca

Please sign in to comment.