You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
So you want to contribute to a Puppet module: Great! Below are some instructions to get you started doing
4
+
that very thing while setting expectations around code quality as well as a few tips for making the
5
+
process as easy as possible.
5
6
6
-
- Make commits of logical units.
7
+
### Table of Contents
7
8
8
-
- Check for unnecessary whitespace with "git diff --check" before
9
-
committing.
9
+
1.[Getting Started](#getting-started)
10
+
1.[Commit Checklist](#commit-checklist)
11
+
1.[Submission](#submission)
12
+
1.[More about commits](#more-about-commits)
13
+
1.[Testing](#testing)
14
+
-[Running Tests](#running-tests)
15
+
-[Writing Tests](#writing-tests)
16
+
1.[Get Help](#get-help)
10
17
11
-
- Commit using Unix line endings (check the settings around "crlf" in
12
-
git-config(1)).
18
+
## Getting Started
13
19
14
-
- Do not check in commented out code or unneeded files.
20
+
- Fork the module repository on GitHub and clone to your workspace
15
21
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.
22
+
- Make your changes!
19
23
20
-
- Associate the issue in the message. The first line should include
21
-
the issue number in the form "(#XXXX) Rest of message".
24
+
## Commit Checklist
22
25
23
-
-The body should provide a meaningful commit message, which:
26
+
### The Basics
24
27
25
-
- uses the imperative, present tense: "change", not "changed" or
26
-
"changes".
28
+
-[x] my commit is a single logical unit of work
27
29
28
-
- includes motivation for the change, and contrasts its
29
-
implementation with the previous behavior.
30
+
-[x] I have checked for unnecessary whitespace with "git diff --check"
30
31
31
-
- Make sure that you have tests for the bug you are fixing, or
32
-
feature you are adding.
32
+
-[x] my commit does not include commented out code or unneeded files
33
33
34
-
- Make sure the test suites passes after your commit:
35
-
`bundle exec rspec spec/acceptance` More information on [testing](#Testing) below
34
+
### The Content
36
35
37
-
- When introducing a new feature, make sure it is properly
38
-
documented in the README.md
36
+
-[x] my commit includes tests for the bug I fixed or feature I added
39
37
40
-
* Submission:
38
+
-[x] my commit includes appropriate documentation changes if it is introducing a new feature or changing existing functionality
39
+
40
+
-[x] my code passes existing test suites
41
41
42
-
* Pre-requisites:
42
+
### The Commit Message
43
43
44
-
- Make sure you have a [GitHub account](https://github.com/join)
44
+
-[x] the first line of my commit message includes:
45
45
46
-
-[Create a ticket](https://tickets.puppet.com/secure/CreateIssue!default.jspa), or [watch the ticket](https://tickets.puppet.com/browse/) you are patching for.
46
+
-[x] an issue number (if applicable), e.g. "(MODULES-xxxx) This is the first line"
47
+
48
+
-[x] a short description (50 characters is the soft limit, excluding ticket number(s))
47
49
48
-
* Preferred method:
50
+
-[x] the body of my commit message:
49
51
50
-
- Fork the repository on GitHub.
52
+
-[x] is meaningful
51
53
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).
54
+
-[x] uses the imperative, present tense: "change", not "changed" or "changes"
55
55
56
-
- Submit a pull request to the repository in the puppetlabs
57
-
organization.
56
+
-[x] includes motivation for the change, and contrasts its implementation with the previous behavior
58
57
59
-
The long version
60
-
================
58
+
## Submission
59
+
60
+
### Pre-requisites
61
+
62
+
- Make sure you have a [GitHub account](https://github.com/join)
63
+
64
+
-[Create a ticket](https://tickets.puppet.com/secure/CreateIssue!default.jspa), or [watch the ticket](https://tickets.puppet.com/browse/) you are patching for.
65
+
66
+
### Push and PR
67
+
68
+
- Push your changes to your fork
69
+
70
+
-[Open a Pull Request](https://help.github.com/articles/creating-a-pull-request-from-a-fork/) against the repository in the puppetlabs organization
71
+
72
+
## More about commits
61
73
62
74
1. Make separate commits for logically separate changes.
63
75
@@ -104,37 +116,32 @@ The long version
104
116
GitHub has some pretty good
105
117
[general documentation](http://help.github.com/) on using
In general, after pushing your topic branch up to your
110
122
repository on GitHub, you can switch to the branch in the
111
123
GitHub UI and click "Pull Request" towards the top of the page
112
124
in order to open a pull request.
113
125
126
+
3. Update the related JIRA issue.
114
127
115
-
3. Update the related GitHub issue.
116
-
117
-
If there is a GitHub issue associated with the change you
128
+
If there is a JIRA issue associated with the change you
118
129
submitted, then you should update the ticket to include the
119
130
location of your branch, along with any other commentary you
120
131
may wish to make.
121
132
122
-
Testing
123
-
=======
133
+
# Testing
124
134
125
-
Getting Started
126
-
---------------
135
+
## Getting Started
127
136
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,
137
+
Our Puppet modules provide [`Gemfile`](./Gemfile)s, which can tell a Ruby package manager such as [bundler](http://bundler.io/) what Ruby packages,
130
138
or Gems, are required to build, develop, and test this software.
131
139
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
140
+
Please make sure you have [bundler installed](http://bundler.io/#getting-started) on your system, and then use it to
141
+
install all dependencies needed for this project in the project root by running
135
142
136
143
```shell
137
-
% bundle install
144
+
% bundle install --path .bundle/gems
138
145
Fetching gem metadata from https://rubygems.org/........
139
146
Fetching gem metadata from https://rubygems.org/..
140
147
Using rake (10.1.0)
@@ -148,70 +155,117 @@ Your bundle is complete!
148
155
Use `bundle show [gemname]` to see where a bundled gem is installed.
149
156
```
150
157
151
-
NOTE some systems may require you to run this command with sudo.
158
+
NOTE: some systems may require you to run this command with sudo.
152
159
153
160
If you already have those gems installed, make sure they are up-to-date:
154
161
155
162
```shell
156
163
% bundle update
157
164
```
158
165
159
-
With all dependencies in place and up-to-date we can now run the tests:
166
+
## Running Tests
167
+
168
+
With all dependencies in place and up-to-date, run the tests:
169
+
170
+
### Unit Tests
160
171
161
172
```shell
162
173
% bundle exec rake spec
163
174
```
164
175
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),
176
+
This executes all the [rspec tests](http://rspec-puppet.com/) in the directories defined [here](https://github.com/puppetlabs/puppetlabs_spec_helper/blob/699d9fbca1d2489bff1736bb254bb7b7edb32c74/lib/puppetlabs_spec_helper/rake_tasks.rb#L17) and so on.
177
+
rspec tests may have the same kind of dependencies as the module they are testing. Although the module defines these dependencies in its [metadata.json](./metadata.json),
169
178
rspec tests define them in [.fixtures.yml](./fixtures.yml).
170
179
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.
180
+
### Acceptance Tests
181
+
182
+
Some Puppet modules also come with acceptance tests, which use [beaker][]. These tests spin up a virtual machine under
183
+
[VirtualBox](https://www.virtualbox.org/), controlled with [Vagrant](http://www.vagrantup.com/), to simulate scripted test
184
+
scenarios. In order to run these, you need both Virtualbox and Vagrant installed on your system.
177
185
178
-
You can run them by issuing the following command
186
+
Run the tests by issuing the following command
179
187
180
188
```shell
181
189
% bundle exec rake spec_clean
182
190
% bundle exec rspec spec/acceptance
183
191
```
184
192
185
193
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)
194
+
install Puppet, copy this module, and install its dependencies per [spec/spec_helper_acceptance.rb](./spec/spec_helper_acceptance.rb)
187
195
and then run all the tests under [spec/acceptance](./spec/acceptance).
188
196
189
-
Writing Tests
190
-
-------------
197
+
## Writing Tests
198
+
199
+
### Unit Tests
191
200
192
-
XXX getting started writing tests.
201
+
When writing unit tests for Puppet, [rspec-puppet][] is your best friend. It provides tons of helper methods for testing your manifests against a
202
+
catalog (e.g. contain_file, contain_package, with_params, etc). It would be ridiculous to try and top rspec-puppet's [documentation][rspec-puppet_docs]
203
+
but here's a tiny sample:
193
204
194
-
If you have commit access to the repository
195
-
===========================================
205
+
Sample manifest:
196
206
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.
207
+
```puppet
208
+
file { "a test file":
209
+
ensure => present,
210
+
path => "/etc/sample",
211
+
}
212
+
```
213
+
214
+
Sample test:
202
215
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.
216
+
```ruby
217
+
it 'does a thing'do
218
+
expect(subject).to contain_file("a test file").with({:path => "/etc/sample"})
219
+
end
220
+
```
206
221
222
+
### Acceptance Tests
223
+
224
+
Writing acceptance tests for Puppet involves [beaker][] and its cousin [beaker-rspec][]. A common pattern for acceptance tests is to create a test manifest, apply it
225
+
twice to check for idempotency or errors, then run expectations.
The record of someone performing the merge is the record that they performed the code review. Again, this should be someone other than the author of the topic branch.
216
254
255
+
# Get Help
256
+
257
+
### On the web
258
+
* [Puppet help messageboard](http://puppet.com/community/get-help)
0 commit comments