39
|
1 Checklist (and a short version for the impatient)
|
|
2 =================================================
|
|
3
|
|
4 * Commits:
|
|
5
|
|
6 - Make commits of logical units.
|
|
7
|
|
8 - Check for unnecessary whitespace with "git diff --check" before
|
|
9 committing.
|
|
10
|
|
11 - Commit using Unix line endings (check the settings around "crlf" in
|
|
12 git-config(1)).
|
|
13
|
|
14 - Do not check in commented out code or unneeded files.
|
|
15
|
|
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.
|
|
19
|
|
20 - Associate the issue in the message. The first line should include
|
|
21 the issue number in the form "(#XXXX) Rest of message".
|
|
22
|
|
23 - The body should provide a meaningful commit message, which:
|
|
24
|
|
25 - uses the imperative, present tense: "change", not "changed" or
|
|
26 "changes".
|
|
27
|
|
28 - includes motivation for the change, and contrasts its
|
|
29 implementation with the previous behavior.
|
|
30
|
|
31 - Make sure that you have tests for the bug you are fixing, or
|
|
32 feature you are adding.
|
|
33
|
|
34 - Make sure the test suites passes after your commit:
|
|
35 `bundle exec rspec spec/acceptance` More information on [testing](#Testing) below
|
|
36
|
|
37 - When introducing a new feature, make sure it is properly
|
|
38 documented in the README.md
|
|
39
|
|
40 * Submission:
|
|
41
|
|
42 * Pre-requisites:
|
|
43
|
|
44 - Make sure you have a [GitHub account](https://github.com/join)
|
|
45
|
|
46 - [Create a ticket](https://tickets.puppetlabs.com/secure/CreateIssue!default.jspa), or [watch the ticket](https://tickets.puppetlabs.com/browse/) you are patching for.
|
|
47
|
|
48 * Preferred method:
|
|
49
|
|
50 - Fork the repository on GitHub.
|
|
51
|
|
52 - Push your changes to a topic branch in your fork of the
|
|
53 repository. (the format ticket/1234-short_description_of_change is
|
|
54 usually preferred for this project).
|
|
55
|
|
56 - Submit a pull request to the repository in the puppetlabs
|
|
57 organization.
|
|
58
|
|
59 The long version
|
|
60 ================
|
|
61
|
|
62 1. Make separate commits for logically separate changes.
|
|
63
|
|
64 Please break your commits down into logically consistent units
|
|
65 which include new or changed tests relevant to the rest of the
|
|
66 change. The goal of doing this is to make the diff easier to
|
|
67 read for whoever is reviewing your code. In general, the easier
|
|
68 your diff is to read, the more likely someone will be happy to
|
|
69 review it and get it into the code base.
|
|
70
|
|
71 If you are going to refactor a piece of code, please do so as a
|
|
72 separate commit from your feature or bug fix changes.
|
|
73
|
|
74 We also really appreciate changes that include tests to make
|
|
75 sure the bug is not re-introduced, and that the feature is not
|
|
76 accidentally broken.
|
|
77
|
|
78 Describe the technical detail of the change(s). If your
|
|
79 description starts to get too long, that is a good sign that you
|
|
80 probably need to split up your commit into more finely grained
|
|
81 pieces.
|
|
82
|
|
83 Commits which plainly describe the things which help
|
|
84 reviewers check the patch and future developers understand the
|
|
85 code are much more likely to be merged in with a minimum of
|
|
86 bike-shedding or requested changes. Ideally, the commit message
|
|
87 would include information, and be in a form suitable for
|
|
88 inclusion in the release notes for the version of Puppet that
|
|
89 includes them.
|
|
90
|
|
91 Please also check that you are not introducing any trailing
|
|
92 whitespace or other "whitespace errors". You can do this by
|
|
93 running "git diff --check" on your changes before you commit.
|
|
94
|
|
95 2. Sending your patches
|
|
96
|
|
97 To submit your changes via a GitHub pull request, we _highly_
|
|
98 recommend that you have them on a topic branch, instead of
|
|
99 directly on "master".
|
|
100 It makes things much easier to keep track of, especially if
|
|
101 you decide to work on another thing before your first change
|
|
102 is merged in.
|
|
103
|
|
104 GitHub has some pretty good
|
|
105 [general documentation](http://help.github.com/) on using
|
|
106 their site. They also have documentation on
|
|
107 [creating pull requests](http://help.github.com/send-pull-requests/).
|
|
108
|
|
109 In general, after pushing your topic branch up to your
|
|
110 repository on GitHub, you can switch to the branch in the
|
|
111 GitHub UI and click "Pull Request" towards the top of the page
|
|
112 in order to open a pull request.
|
|
113
|
|
114
|
|
115 3. Update the related GitHub issue.
|
|
116
|
|
117 If there is a GitHub issue associated with the change you
|
|
118 submitted, then you should update the ticket to include the
|
|
119 location of your branch, along with any other commentary you
|
|
120 may wish to make.
|
|
121
|
|
122 Testing
|
|
123 =======
|
|
124
|
|
125 Getting Started
|
|
126 ---------------
|
|
127
|
|
128 Our puppet modules provide [`Gemfile`](./Gemfile)s which can tell a ruby
|
|
129 package manager such as [bundler](http://bundler.io/) what Ruby packages,
|
|
130 or Gems, are required to build, develop, and test this software.
|
|
131
|
|
132 Please make sure you have [bundler installed](http://bundler.io/#getting-started)
|
|
133 on your system, then use it to install all dependencies needed for this project,
|
|
134 by running
|
|
135
|
|
136 ```shell
|
|
137 % bundle install
|
|
138 Fetching gem metadata from https://rubygems.org/........
|
|
139 Fetching gem metadata from https://rubygems.org/..
|
|
140 Using rake (10.1.0)
|
|
141 Using builder (3.2.2)
|
|
142 -- 8><-- many more --><8 --
|
|
143 Using rspec-system-puppet (2.2.0)
|
|
144 Using serverspec (0.6.3)
|
|
145 Using rspec-system-serverspec (1.0.0)
|
|
146 Using bundler (1.3.5)
|
|
147 Your bundle is complete!
|
|
148 Use `bundle show [gemname]` to see where a bundled gem is installed.
|
|
149 ```
|
|
150
|
|
151 NOTE some systems may require you to run this command with sudo.
|
|
152
|
|
153 If you already have those gems installed, make sure they are up-to-date:
|
|
154
|
|
155 ```shell
|
|
156 % bundle update
|
|
157 ```
|
|
158
|
|
159 With all dependencies in place and up-to-date we can now run the tests:
|
|
160
|
|
161 ```shell
|
|
162 % rake spec
|
|
163 ```
|
|
164
|
|
165 This will execute all the [rspec tests](http://rspec-puppet.com/) tests
|
|
166 under [spec/defines](./spec/defines), [spec/classes](./spec/classes),
|
|
167 and so on. rspec tests may have the same kind of dependencies as the
|
|
168 module they are testing. While the module defines in its [Modulefile](./Modulefile),
|
|
169 rspec tests define them in [.fixtures.yml](./fixtures.yml).
|
|
170
|
|
171 Some puppet modules also come with [beaker](https://github.com/puppetlabs/beaker)
|
|
172 tests. These tests spin up a virtual machine under
|
|
173 [VirtualBox](https://www.virtualbox.org/)) with, controlling it with
|
|
174 [Vagrant](http://www.vagrantup.com/) to actually simulate scripted test
|
|
175 scenarios. In order to run these, you will need both of those tools
|
|
176 installed on your system.
|
|
177
|
|
178 You can run them by issuing the following command
|
|
179
|
|
180 ```shell
|
|
181 % rake spec_clean
|
|
182 % rspec spec/acceptance
|
|
183 ```
|
|
184
|
|
185 This will now download a pre-fabricated image configured in the [default node-set](./spec/acceptance/nodesets/default.yml),
|
|
186 install puppet, copy this module and install its dependencies per [spec/spec_helper_acceptance.rb](./spec/spec_helper_acceptance.rb)
|
|
187 and then run all the tests under [spec/acceptance](./spec/acceptance).
|
|
188
|
|
189 Writing Tests
|
|
190 -------------
|
|
191
|
|
192 XXX getting started writing tests.
|
|
193
|
|
194 If you have commit access to the repository
|
|
195 ===========================================
|
|
196
|
|
197 Even if you have commit access to the repository, you will still need to
|
|
198 go through the process above, and have someone else review and merge
|
|
199 in your changes. The rule is that all changes must be reviewed by a
|
|
200 developer on the project (that did not write the code) to ensure that
|
|
201 all changes go through a code review process.
|
|
202
|
|
203 Having someone other than the author of the topic branch recorded as
|
|
204 performing the merge is the record that they performed the code
|
|
205 review.
|
|
206
|
|
207
|
|
208 Additional Resources
|
|
209 ====================
|
|
210
|
|
211 * [Getting additional help](http://puppetlabs.com/community/get-help)
|
|
212
|
|
213 * [Writing tests](http://projects.puppetlabs.com/projects/puppet/wiki/Development_Writing_Tests)
|
|
214
|
|
215 * [Patchwork](https://patchwork.puppetlabs.com)
|
|
216
|
|
217 * [General GitHub documentation](http://help.github.com/)
|
|
218
|
|
219 * [GitHub pull request documentation](http://help.github.com/send-pull-requests/)
|
|
220
|