Mercurial > repos > other > Puppet
annotate modules/stdlib/CONTRIBUTING.md @ 246:c3fa3d65aa83
Update configs for Puppet 6
This *should* all be backward compatible
| author | IBBoard <dev@ibboard.co.uk> |
|---|---|
| date | Sat, 21 Dec 2019 14:19:47 -0500 |
| parents | addb0ea390a1 |
| children | c42fb28cff86 |
| rev | line source |
|---|---|
| 37 | 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: | |
|
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
24 |
| 37 | 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 | |
|
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
36 |
| 37 | 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. | |
|
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
51 |
| 37 | 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. | |
|
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
63 |
| 37 | 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. | |
|
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
77 |
| 37 | 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/). | |
|
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
108 |
| 37 | 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 | |
|
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
135 |
| 37 | 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 ``` | |
|
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
150 |
| 37 | 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: | |
|
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
154 |
| 37 | 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 ``` | |
|
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
164 |
| 37 | 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. | |
|
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
177 |
| 37 | 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 ------------- | |
|
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
191 |
| 37 | 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. | |
|
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
206 |
| 37 | 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 | |
|
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
217 * [General GitHub documentation](http://help.github.com/) |
| 37 | 218 |
|
0
956e484adc12
Initial public release of Puppet configs
IBBoard <dev@ibboard.co.uk>
parents:
diff
changeset
|
219 * [GitHub pull request documentation](http://help.github.com/send-pull-requests/) |
| 37 | 220 |