Mercurial > repos > other > Puppet
comparison modules/apache/CONTRIBUTING.md @ 0:956e484adc12
Initial public release of Puppet configs
author | IBBoard <dev@ibboard.co.uk> |
---|---|
date | Sat, 16 Aug 2014 19:47:38 +0000 |
parents | |
children | 37675581a273 |
comparison
equal
deleted
inserted
replaced
-1:000000000000 | 0:956e484adc12 |
---|---|
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 - Sign the [Contributor License Agreement](https://cla.puppetlabs.com/) | |
45 | |
46 - Make sure you have a [GitHub account](https://github.com/join) | |
47 | |
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. | |
49 | |
50 * Preferred method: | |
51 | |
52 - Fork the repository on GitHub. | |
53 | |
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). | |
57 | |
58 - Submit a pull request to the repository in the puppetlabs | |
59 organization. | |
60 | |
61 The long version | |
62 ================ | |
63 | |
64 1. Make separate commits for logically separate changes. | |
65 | |
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. | |
72 | |
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. | |
75 | |
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 | |
78 accidentally broken. | |
79 | |
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 | |
83 pieces. | |
84 | |
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 | |
91 includes them. | |
92 | |
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. | |
96 | |
97 2. Sign the Contributor License Agreement | |
98 | |
99 Before we can accept your changes, we do need a signed Puppet | |
100 Labs Contributor License Agreement (CLA). | |
101 | |
102 You can access the CLA via the [Contributor License Agreement link](https://cla.puppetlabs.com/) | |
103 | |
104 If you have any questions about the CLA, please feel free to | |
105 contact Puppet Labs via email at cla-submissions@puppetlabs.com. | |
106 | |
107 3. Sending your patches | |
108 | |
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 | |
114 is merged in. | |
115 | |
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/). | |
120 | |
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. | |
125 | |
126 | |
127 4. Update the related GitHub issue. | |
128 | |
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 | |
132 may wish to make. | |
133 | |
134 Testing | |
135 ======= | |
136 | |
137 Getting Started | |
138 --------------- | |
139 | |
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. | |
143 | |
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, | |
146 by running | |
147 | |
148 ```shell | |
149 % bundle install | |
150 Fetching gem metadata from https://rubygems.org/........ | |
151 Fetching gem metadata from https://rubygems.org/.. | |
152 Using rake (10.1.0) | |
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. | |
161 ``` | |
162 | |
163 NOTE some systems may require you to run this command with sudo. | |
164 | |
165 If you already have those gems installed, make sure they are up-to-date: | |
166 | |
167 ```shell | |
168 % bundle update | |
169 ``` | |
170 | |
171 With all dependencies in place and up-to-date we can now run the tests: | |
172 | |
173 ```shell | |
174 % rake spec | |
175 ``` | |
176 | |
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). | |
182 | |
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. | |
189 | |
190 You can run them by issuing the following command | |
191 | |
192 ```shell | |
193 % rake spec_clean | |
194 % rspec spec/acceptance | |
195 ``` | |
196 | |
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). | |
200 | |
201 Writing Tests | |
202 ------------- | |
203 | |
204 XXX getting started writing tests. | |
205 | |
206 If you have commit access to the repository | |
207 =========================================== | |
208 | |
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. | |
214 | |
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 | |
217 review. | |
218 | |
219 | |
220 Additional Resources | |
221 ==================== | |
222 | |
223 * [Getting additional help](http://projects.puppetlabs.com/projects/puppet/wiki/Getting_Help) | |
224 | |
225 * [Writing tests](http://projects.puppetlabs.com/projects/puppet/wiki/Development_Writing_Tests) | |
226 | |
227 * [Patchwork](https://patchwork.puppetlabs.com) | |
228 | |
229 * [Contributor License Agreement](https://projects.puppetlabs.com/contributor_licenses/sign) | |
230 | |
231 * [General GitHub documentation](http://help.github.com/) | |
232 | |
233 * [GitHub pull request documentation](http://help.github.com/send-pull-requests/) | |
234 |