Commit 2e5b51b4 authored by Tim Smith's avatar Tim Smith
Browse files

Update docs

parent 49b21a92
# Contributing to Chef Cookbooks
We are glad you want to contribute to Chef Cookbooks! The first
step is the desire to improve the project. If you're new to the Chef
community, please read
[How to become a contributor](
on the Supermarket website for more information.
## Quick-contribute
* Create an account on the [Supermarket](
* Sign our contributor agreement (CLA)[online](
* Visit the Github page for the project.
* Fork the repository
* Create a feature branch for your change.
* Create a Pull Request for your change.
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, Chef
Software Inc 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
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]( If
you're contributing on behalf of your employer, have your employer
fill out our
[Corporate CLA](
## Using git
You can get a quick copy of the repository for this cookbook by
running `git clone 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.
If you have another repository in your GitHub account named the same
as the cookbook, we suggest you suffix the repository with -cookbook.
### Branches and Commits
Create a _topic branch_ and a pull request on Github. It is a best
practice to have your commit message have a _summary line_ 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
If your branch has multiple commits, please quash them into a
single commit. If the PR is addressing an issue in the Github issue
tracker, please reference it in the summary line.
[#42] - platform_family and style
* use platform_family for platform checking
* update notifies syntax to "resource_type[resource_name]" instead of
resources() lookup
* #40 - delete config files dropped off by packages in conf.d
* 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.
### More information
Additional help with git is available on the
[Working with Git](
wiki page.
## Functional and Unit Tests
This cookbook is set up to run tests under
[Kitchen-ci's test-kitchen](
It uses Serverspec or Bats to perform integration tests after the node
has been converged.
Test kitchen should run completely without exception using the default
[baseboxes provided by Chef](
Because Test Kitchen creates VirtualBox machines and runs through
every configuration in the Kitchenfile, it may take some time for
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
Chef regularly reviews code contributions and provides suggestions
for improvement in the code itself or the implementation.
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 Chef Cookbook projects 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
Releases of Chef's cookbooks are usually announced on the Chef user
mailing list. Releases of several cookbooks may be batched together
and announced on the [Chef Blog](
## Working with the community
These resources will help you learn more about Chef and connect to
other members of the Chef community:
* [chef]( and
[chef-dev]( mailing
* #chef and #chef-hacking IRC channels on
* [Community Cookbook site](
* [Chef wiki](
* Chef, Inc [product page](
## Cookbook Contribution Do's and Don't's
Please do include tests for your contribution. If you need help, ask
on the [chef-dev mailing list](
or the [#chef-hacking IRC channel](
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).
git commit -m 'Updated pool resource to correctly delete.'
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.
Please do not modify the version number in the metadata.rb, Chef
Software, Inc will select the appropriate version based on the release
cycle information above.
Please do not update the for a new version. Not all
changes to a cookbook may be merged and released in the same versions.
Chef Software will update the when releasing a new version of
the cookbook.
Please refer to
A ruby environment with Bundler installed is a prerequisite for using
the testing harness shipped with this cookbook. At the time of this
writing, it works with Ruby 2.0 and Bundler 1.5.3. All programs
involved, with the exception of Vagrant, can be installed by cd'ing
into the parent directory of this cookbook and running "bundle install"
The Rakefile ships with a number of tasks, each of which can be ran
individually, or in groups. Typing "rake" by itself will perform style
checks with Rubocop and Foodcritic, ChefSpec with rspec, and
integration with Test Kitchen using the Vagrant driver by
default.Alternatively, integration tests can be ran with Test Kitchen
cloud drivers.
$ rake -T
rake integration:cloud # Run Test Kitchen with cloud plugins
rake integration:vagrant # Run Test Kitchen with Vagrant
rake spec # Run ChefSpec examples
rake style # Run all style checks
rake style:chef # Lint Chef cookbooks
rake style:ruby # Run Ruby style checks
rake travis # Run all tests on Travis
Style Testing
Ruby style tests can be performed by Rubocop by issuing either
bundle exec rubocop
rake style:ruby
Chef style tests can be performed with Foodcritic by issuing either
bundle exec foodcritic
rake style:chef
Spec Testing
Unit testing is done by running Rspec examples. Rspec will test any
libraries, then test recipes using ChefSpec. This works by compiling a
recipe (but not converging it), and allowing the user to make
assertions about the resource_collection.
Integration Testing
Integration testing is performed by Test Kitchen. Test Kitchen will
use either the Vagrant driver or various cloud drivers to instantiate
machines and apply cookbooks. After a successful converge, tests are
uploaded and ran out of band of Chef. Tests should be designed to
ensure that a recipe has accomplished its goal.
Integration Testing using Vagrant
Integration tests can be performed on a local workstation using
Virtualbox or VMWare. Detailed instructions for setting this up can be
found at the [Bento]( project web site.
Integration tests using Vagrant can be performed with either
bundle exec kitchen test
rake integration:vagrant
Integration Testing using Cloud providers
Integration tests can be performed on cloud providers using
Test Kitchen plugins. This cookbook ships a ``````
that references environmental variables present in the shell that
```kitchen test``` is ran from. These usually contain authentication
tokens for driving IaaS APIs, as well as the paths to ssh private keys
needed for Test Kitchen log into them after they've been created.
Examples of environment variables being set in ```~/.bash_profile```:
# digital_ocean
export DIGITAL_OCEAN_CLIENT_ID='your_bits_here'
export DIGITAL_OCEAN_API_KEY='your_bits_here'
export DIGITAL_OCEAN_SSH_KEY_IDS='your_bits_here'
# aws
export AWS_ACCESS_KEY_ID='your_bits_here'
export AWS_SECRET_ACCESS_KEY='your_bits_here'
export AWS_KEYPAIR_NAME='your_bits_here'
# joyent
export SDC_CLI_ACCOUNT='your_bits_here'
export SDC_CLI_IDENTITY='your_bits_here'
export SDC_CLI_KEY_ID='your_bits_here'
Integration tests using cloud drivers can be performed with either
bundle exec kitchen test
rake integration:cloud
Digital Ocean Hint
At the time of this writing, you cannot find the numerical values
needed for your SSH_KEY_IDS from the GUI. Instead, you will need to
access the API from the command line.
curl -L ''
Words about .travis.yml
In order for Travis to perform integration tests on public cloud
providers, two major things need to happen. First, the environment
variables referenced by `````` need to be made
available. Second, the private half of the ssh keys needed to log into
machines need to be dropped off on the machine.
The first part is straight forward. The travis gem can encrypt
environment variables against the public key on the Travis repository
and add them to the .travis.yml.
gem install travis
travis encrypt AWS_ACCESS_KEY_ID='your_bits_here' --add
travis encrypt AWS_SECRET_ACCESS_'your_bits_here' --add
travis encrypt AWS_KEYPAIR_NAME='your_bits_here' --add
travis encrypt EC2_SSH_KEY_PATH='~/.ssh/id_ec2.pem' --add
travis encrypt DIGITAL_OCEAN_CLIENT_ID='your_bits_here' --add
travis encrypt DIGITAL_OCEAN_API_KEY='your_bits_here' --add
travis encrypt DIGITAL_OCEAN_SSH_KEY_IDS='your_bits_here' --add
travis encrypt DIGITAL_OCEAN_SSH_KEY_PATH='~/.ssh/id_do.pem' --add
The second part is a little more complicated. Travis ENV variables are
restricted to 90 bytes, and will not fit an entire SSH key. This can
be worked around by breaking them up into 90 byte chunks, stashing
them into ENV variables, then digging them out in the
```before_install``` section of .travis.yml
Here is an AWK script to do the encoding.
base64 ~/.ssh/travisci_cook_digitalocean.pem | \
awk '{
for( i=1; i<length; i=i+90 ) {
system("travis encrypt DO_KEY_CHUNK_" j "=" substr($0, i, 90) " --add");
base64 ~/.ssh/travisci_cook_ec2.pem | \
awk '{
for( i=1; i<length; i=i+90 ) {
system("travis encrypt EC2_KEY_CHUNK_" j "=" substr($0, i, 90)" --add");
Then in .travis.yml:
- echo -n $DO_KEY_CHUNK_{0..30} >> ~/.ssh/id_do.base64
- cat ~/.ssh/id_do.base64 | tr -d ' ' | base64 --decode > ~/.ssh/id_do.pem
- echo -n $EC2_KEY_CHUNK_{0..30} >> ~/.ssh/id_ec2.base64
- cat ~/.ssh/id_ec2.base64 | tr -d ' ' | base64 --decode > ~/.ssh/id_ec2.pem
Please refer to
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment