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 | % bundle exec 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 | % bundle exec rake spec_clean
|
---|
182 | % bundle exec 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://puppet.com/community/get-help)
|
---|
212 |
|
---|
213 | * [Writing tests](https://docs.puppet.com/guides/module_guides/bgtm.html#step-three-module-testing)
|
---|
214 |
|
---|
215 | * [General GitHub documentation](http://help.github.com/)
|
---|
216 |
|
---|
217 | * [GitHub pull request documentation](http://help.github.com/send-pull-requests/)
|
---|
218 |
|
---|