CONTRIBUTING.md 9.45 KB
Newer Older
Sean OMeara's avatar
Sean OMeara committed
1
# Contributing to Chef Software Cookbooks
jtimberman's avatar
jtimberman committed
2

Sean OMeara's avatar
Sean OMeara committed
3
We are glad you want to contribute to Chef Software Cookbooks! The first
jtimberman's avatar
jtimberman committed
4
5
6
step is the desire to improve the project.

You can find additional information about
nathenharvey's avatar
nathenharvey committed
7
8
[contributing to cookbooks](https://docs.chef.io/community_contributions.html)
on the Chef Docs site.
jtimberman's avatar
jtimberman committed
9
10
11

## Quick-contribute

nathenharvey's avatar
nathenharvey committed
12
13
14
15
* Create an account on [GitHub](http://github.com).
* Create an account on the [Chef Supermarket](https://supermarket.chef.io/).
* [Become a contributor](https://supermarket.chef.io/become-a-contributor) by 
signing our Contributor License Agreement (CLA).
Tim Smith's avatar
Tim Smith committed
16
17
* Create a [pull request for your change on
GitHub](https://github.com/opscode-cookbooks/aws/pulls).
jtimberman's avatar
jtimberman committed
18

Tim Smith's avatar
Tim Smith committed
19
We try to regularly review contributions and will get back to you if we have
jtimberman's avatar
jtimberman committed
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
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.

Sean OMeara's avatar
Sean OMeara committed
36
To make a good faith effort to ensure these criteria are met, Chef
Tim Smith's avatar
Tim Smith committed
37
Software Inc requires a Contributor License Agreement (CLA) or a Corporate
jtimberman's avatar
jtimberman committed
38
39
40
41
42
43
44
45
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.

nathenharvey's avatar
nathenharvey committed
46
47
You can complete our contributor license agreement (CLA)
[ online at the Chef Supermarket](https://supermarket.chef.io).
jtimberman's avatar
jtimberman committed
48
49
If you're contributing on behalf of your employer, have your employer
fill out our
Tim Smith's avatar
Tim Smith committed
50
[Corporate Contributor License Agreement
nathenharvey's avatar
nathenharvey committed
51
(CCLA)](https://supermarket.chef.io/ccla-signatures/new) instead.
jtimberman's avatar
jtimberman committed
52

nathenharvey's avatar
nathenharvey committed
53
## Ticket Tracker (GitHub Issues)
jtimberman's avatar
jtimberman committed
54

nathenharvey's avatar
nathenharvey committed
55
56
57
The [ticket tracker](https://github.com/opscode-cookbooks/erlang/issues) is 
the most important documentation for the code base. It provides significant 
historical information, such as:
jtimberman's avatar
jtimberman committed
58
59
60
61
62
63
64
65
66
67
68

* 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 repository for this cookbook by
running `git clone
Tim Smith's avatar
Tim Smith committed
69
git://github.com/opscode-cookbooks/COOKBOOKNAME.git`.
jtimberman's avatar
jtimberman committed
70

Tim Smith's avatar
Tim Smith committed
71
For collaboration purposes, it is best if you create a GitHub account
jtimberman's avatar
jtimberman committed
72
and fork the repository to your own account. Once you do this you will
Tim Smith's avatar
Tim Smith committed
73
be able to push your changes to your GitHub repository for others to
jtimberman's avatar
jtimberman committed
74
75
76
see and use.

If you have another repository in your GitHub account named the same
Tim Smith's avatar
Tim Smith committed
77
as the cookbook, we suggest you suffix the repository with `-cookbook`.
jtimberman's avatar
jtimberman committed
78
79
80
81

### Branches and Commits

You should submit your patch as a git branch named after the ticket,
Tim Smith's avatar
Tim Smith committed
82
such as GH-22. This is called a _topic branch_ and allows users to
jtimberman's avatar
jtimberman committed
83
84
85
86
87
88
89
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.

Tim Smith's avatar
Tim Smith committed
90
    [GH-22] - platform_family and style
jtimberman's avatar
jtimberman committed
91
92
93
94

    * use platform_family for platform checking
    * update notifies syntax to "resource_type[resource_name]" instead of
      resources() lookup
Tim Smith's avatar
Tim Smith committed
95
    * GH-692 - delete config files dropped off by packages in conf.d
jtimberman's avatar
jtimberman committed
96
97
98
99
100
101
102
103
    * dropped debian 4 support because all other platforms have the same
      values, and it is older than "old stable" debian release

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.

Tim Smith's avatar
Tim Smith committed
104
### GitHub and Pull Requests
jtimberman's avatar
jtimberman committed
105

Sean OMeara's avatar
Sean OMeara committed
106
All of Chef's open source cookbook projects are available on
Tim Smith's avatar
Tim Smith committed
107
108
GitHub at either
[http://www.github.com/chef-cookbooks](http://www.github.com/chef-cookbooks) or
nathenharvey's avatar
nathenharvey committed
109
[http://www.github.com/opscode-cookbooks](http://www.github.com/opscode-cookbooks).
jtimberman's avatar
jtimberman committed
110
111
112

### More information

Tim Smith's avatar
Tim Smith committed
113
114
Additional help with git is available on the [Community
Contributions](https://docs.chef.io/community_contributions.html#use-git)
nathenharvey's avatar
nathenharvey committed
115
page on the Chef Docs site.
jtimberman's avatar
jtimberman committed
116
117
118
119

## Functional and Unit Tests

This cookbook is set up to run tests under
nathenharvey's avatar
nathenharvey committed
120
[Test Kitchen](https://github.com/test-kitchen). It
jtimberman's avatar
jtimberman committed
121
122
123
124
uses minitest-chef to run integration tests after the node has been
converged to verify that the state of the node.

Test kitchen should run completely without exception using the default
Sean OMeara's avatar
Sean OMeara committed
125
[baseboxes provided by Chef](https://github.com/chef/bento).
jtimberman's avatar
jtimberman committed
126
Because Test Kitchen creates VirtualBox machines and runs through
Tim Smith's avatar
Tim Smith committed
127
every configuration in the `.kitchen.yml` file, it may take some time for
jtimberman's avatar
jtimberman committed
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
these tests to complete.

If your changes are only for a specific recipe, run only its
configuration with Test Kitchen. If you are adding a new recipe, or
other functionality such as a LWRP or definition, please add
appropriate tests and ensure they run with Test Kitchen.

If any don't pass, investigate them before submitting your patch.

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.

If you need help writing tests, please ask on the Chef Developer's
mailing list, or the #chef-hacking IRC channel.

## Code Review

Sean OMeara's avatar
Sean OMeara committed
155
Chef Software regularly reviews code contributions and provides suggestions
jtimberman's avatar
jtimberman committed
156
157
158
159
for improvement in the code itself or the implementation.

## Release Cycle

Sean OMeara's avatar
Sean OMeara committed
160
The versioning for Chef Software Cookbook projects is X.Y.Z.
jtimberman's avatar
jtimberman committed
161
162
163
164
165
166
167
168
169
170
171
172

* 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

A released version of a cookbook will end in an even number, e.g.
"1.2.4" or "0.8.0". When development for the next version of the
cookbook begins, the "Z" patch number is incremented to the next odd
number, however the next release of the cookbook may be a major or
minor incrementing version.

Sean OMeara's avatar
Sean OMeara committed
173
Releases of Chef's cookbooks are usually announced on the Chef user
jtimberman's avatar
jtimberman committed
174
mailing list. Releases of several cookbooks may be batched together
Sean OMeara's avatar
Sean OMeara committed
175
and announced on the [Chef Software Blog](http://www.chef.io/blog).
jtimberman's avatar
jtimberman committed
176
177
178
179
180
181

## Working with the community

These resources will help you learn more about Chef and connect to
other members of the Chef community:

Sean OMeara's avatar
Sean OMeara committed
182
183
* [chef](http://lists.chef.io/sympa/info/chef) and
  [chef-dev](http://lists.chef.io/sympa/info/chef-dev) mailing
jtimberman's avatar
jtimberman committed
184
185
  lists
* #chef and #chef-hacking IRC channels on irc.freenode.net
nathenharvey's avatar
nathenharvey committed
186
187
* [Supermarket site](http://supermarket.chef.io)
* [Chef Docs](http://docs.chef.io)
Sean OMeara's avatar
Sean OMeara committed
188
* Chef Software Chef [product page](http://www.chef.io/chef)
jtimberman's avatar
jtimberman committed
189
190
191
192
193
194


## Cookbook Contribution Do's and Don't's

Please do include tests for your contribution. If you need help, ask
on the
Sean OMeara's avatar
Sean OMeara committed
195
[chef-dev mailing list](http://lists.chef.io/sympa/info/chef-dev)
jtimberman's avatar
jtimberman committed
196
or the
Sean OMeara's avatar
Sean OMeara committed
197
[#chef-hacking IRC channel](http://community.chef.io/chat/chef-hacking).
jtimberman's avatar
jtimberman committed
198
199
200
201
202
203
204
205
206
207
Not all platforms that a cookbook supports may be supported by Test
Kitchen. Please provide evidence of testing your contribution if it
isn't trivial so we don't have to duplicate effort in testing. Chef
10.14+ "doc" formatted output is sufficient.

Please do indicate new platform (families) or platform versions in the
commit message, and update the relevant ticket.

If a contribution adds new platforms or platform versions, indicate
such in the body of the commit message(s), and update the relevant
nathenharvey's avatar
nathenharvey committed
208
209
issues. When writing commit messages, it is helpful for others if
you indicate the issue. For example:
jtimberman's avatar
jtimberman committed
210

nathenharvey's avatar
nathenharvey committed
211
    git commit -m '[ISSUE-1041] - Updated pool resource to correctly
jtimberman's avatar
jtimberman committed
212
213
214
215
216
217
218
219
220
221
222
223
    delete.'

Please do use [foodcritic](http://acrmp.github.com/foodcritic) to
lint-check the cookbook. Except FC007, it should pass all correctness
rules. FC007 is okay as long as the dependent cookbooks are *required*
for the default behavior of the cookbook, such as to support an
uncommon platform, secondary recipe, etc.

Please do ensure that your changes do not break or modify behavior for
other platforms supported by the cookbook. For example if your changes
are for Debian, make sure that they do not break on CentOS.

Tim Smith's avatar
Tim Smith committed
224
Please do **not** modify the version number in the `metadata.rb`, Chef
jtimberman's avatar
jtimberman committed
225
226
227
will select the appropriate version based on the release cycle
information above.

Tim Smith's avatar
Tim Smith committed
228
Please do **not** update the `CHANGELOG.md` for a new version. Not all
jtimberman's avatar
jtimberman committed
229
changes to a cookbook may be merged and released in the same versions.
Tim Smith's avatar
Tim Smith committed
230
Chef Software will update the `CHANGELOG.md` when releasing a new version of
jtimberman's avatar
jtimberman committed
231
the cookbook.