1 Checklist (and a short version for the impatient)
2 =================================================
6 - Make commits of logical units.
8 - Check for unnecessary whitespace with "git diff --check" before
11 - Commit using Unix line endings (check the settings around "crlf" in
14 - Do not check in commented out code or unneeded files.
16 - The first line of the commit message should be a short
17 description (50 characters is the soft limit, excluding ticket
18 number(s)), and should skip the full stop.
20 - Associate the issue in the message. The first line should include
21 the issue number in the form "(#XXXX) Rest of message".
23 - The body should provide a meaningful commit message, which:
25 - uses the imperative, present tense: "change", not "changed" or
28 - includes motivation for the change, and contrasts its
29 implementation with the previous behavior.
31 - Make sure that you have tests for the bug you are fixing, or
32 feature you are adding.
34 - Make sure the test suites passes after your commit:
35 `bundle exec rspec spec/acceptance` More information on [testing](#Testing) below
37 - When introducing a new feature, make sure it is properly
38 documented in the README.md
44 - Sign the [Contributor License Agreement](https://cla.puppetlabs.com/)
46 - Make sure you have a [GitHub account](https://github.com/join)
48 - [Create a ticket](http://projects.puppetlabs.com/projects/modules/issues/new), or [watch the ticket](http://projects.puppetlabs.com/projects/modules/issues) you are patching for.
52 - Fork the repository on GitHub.
54 - Push your changes to a topic branch in your fork of the
55 repository. (the format ticket/1234-short_description_of_change is
56 usually preferred for this project).
58 - Submit a pull request to the repository in the puppetlabs
64 1. Make separate commits for logically separate changes.
66 Please break your commits down into logically consistent units
67 which include new or changed tests relevant to the rest of the
68 change. The goal of doing this is to make the diff easier to
69 read for whoever is reviewing your code. In general, the easier
70 your diff is to read, the more likely someone will be happy to
71 review it and get it into the code base.
73 If you are going to refactor a piece of code, please do so as a
74 separate commit from your feature or bug fix changes.
76 We also really appreciate changes that include tests to make
77 sure the bug is not re-introduced, and that the feature is not
80 Describe the technical detail of the change(s). If your
81 description starts to get too long, that is a good sign that you
82 probably need to split up your commit into more finely grained
85 Commits which plainly describe the things which help
86 reviewers check the patch and future developers understand the
87 code are much more likely to be merged in with a minimum of
88 bike-shedding or requested changes. Ideally, the commit message
89 would include information, and be in a form suitable for
90 inclusion in the release notes for the version of Puppet that
93 Please also check that you are not introducing any trailing
94 whitespace or other "whitespace errors". You can do this by
95 running "git diff --check" on your changes before you commit.
97 2. Sign the Contributor License Agreement
99 Before we can accept your changes, we do need a signed Puppet
100 Labs Contributor License Agreement (CLA).
102 You can access the CLA via the [Contributor License Agreement link](https://cla.puppetlabs.com/)
104 If you have any questions about the CLA, please feel free to
105 contact Puppet Labs via email at cla-submissions@puppetlabs.com.
107 3. Sending your patches
109 To submit your changes via a GitHub pull request, we _highly_
110 recommend that you have them on a topic branch, instead of
111 directly on "master".
112 It makes things much easier to keep track of, especially if
113 you decide to work on another thing before your first change
116 GitHub has some pretty good
117 [general documentation](http://help.github.com/) on using
118 their site. They also have documentation on
119 [creating pull requests](http://help.github.com/send-pull-requests/).
121 In general, after pushing your topic branch up to your
122 repository on GitHub, you can switch to the branch in the
123 GitHub UI and click "Pull Request" towards the top of the page
124 in order to open a pull request.
127 4. Update the related GitHub issue.
129 If there is a GitHub issue associated with the change you
130 submitted, then you should update the ticket to include the
131 location of your branch, along with any other commentary you
140 Our puppet modules provide [`Gemfile`](./Gemfile)s which can tell a ruby
141 package manager such as [bundler](http://bundler.io/) what Ruby packages,
142 or Gems, are required to build, develop, and test this software.
144 Please make sure you have [bundler installed](http://bundler.io/#getting-started)
145 on your system, then use it to install all dependencies needed for this project,
150 Fetching gem metadata from https://rubygems.org/........
151 Fetching gem metadata from https://rubygems.org/..
153 Using builder (3.2.2)
154 -- 8><-- many more --><8 --
155 Using rspec-system-puppet (2.2.0)
156 Using serverspec (0.6.3)
157 Using rspec-system-serverspec (1.0.0)
158 Using bundler (1.3.5)
159 Your bundle is complete!
160 Use `bundle show [gemname]` to see where a bundled gem is installed.
163 NOTE some systems may require you to run this command with sudo.
165 If you already have those gems installed, make sure they are up-to-date:
171 With all dependencies in place and up-to-date we can now run the tests:
177 This will execute all the [rspec tests](http://rspec-puppet.com/) tests
178 under [spec/defines](./spec/defines), [spec/classes](./spec/classes),
179 and so on. rspec tests may have the same kind of dependencies as the
180 module they are testing. While the module defines in its [Modulefile](./Modulefile),
181 rspec tests define them in [.fixtures.yml](./fixtures.yml).
183 Some puppet modules also come with [beaker](https://github.com/puppetlabs/beaker)
184 tests. These tests spin up a virtual machine under
185 [VirtualBox](https://www.virtualbox.org/)) with, controlling it with
186 [Vagrant](http://www.vagrantup.com/) to actually simulate scripted test
187 scenarios. In order to run these, you will need both of those tools
188 installed on your system.
190 You can run them by issuing the following command
194 % rspec spec/acceptance
197 This will now download a pre-fabricated image configured in the [default node-set](./spec/acceptance/nodesets/default.yml),
198 install puppet, copy this module and install its dependencies per [spec/spec_helper_acceptance.rb](./spec/spec_helper_acceptance.rb)
199 and then run all the tests under [spec/acceptance](./spec/acceptance).
204 XXX getting started writing tests.
206 If you have commit access to the repository
207 ===========================================
209 Even if you have commit access to the repository, you will still need to
210 go through the process above, and have someone else review and merge
211 in your changes. The rule is that all changes must be reviewed by a
212 developer on the project (that did not write the code) to ensure that
213 all changes go through a code review process.
215 Having someone other than the author of the topic branch recorded as
216 performing the merge is the record that they performed the code
223 * [Getting additional help](http://projects.puppetlabs.com/projects/puppet/wiki/Getting_Help)
225 * [Writing tests](http://projects.puppetlabs.com/projects/puppet/wiki/Development_Writing_Tests)
227 * [Patchwork](https://patchwork.puppetlabs.com)
229 * [Contributor License Agreement](https://projects.puppetlabs.com/contributor_licenses/sign)
231 * [General GitHub documentation](http://help.github.com/)
233 * [GitHub pull request documentation](http://help.github.com/send-pull-requests/)