Mercurial > repos > other > Puppet

annotate modules/concat/CONTRIBUTING.md @ 275:d9352a684e62

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Mass update of modules to remove deprecation warnings
author IBBoard <dev@ibboard.co.uk>
date Sun, 26 Jan 2020 11:36:07 +0000
parents 37675581a273
children adf6fe9bbc17
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
275
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
1 # Contributing to Puppet modules
36
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
2
275
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
3 So you want to contribute to a Puppet module: Great! Below are some instructions to get you started doing
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
4 that very thing while setting expectations around code quality as well as a few tips for making the
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
5 process as easy as possible.
36
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
6
275
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
7 ### Table of Contents
36
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
8
275
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
9 1. [Getting Started](#getting-started)
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
10 1. [Commit Checklist](#commit-checklist)
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
11 1. [Submission](#submission)
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
12 1. [More about commits](#more-about-commits)
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
13 1. [Testing](#testing)
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
14 - [Running Tests](#running-tests)
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
15 - [Writing Tests](#writing-tests)
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
16 1. [Get Help](#get-help)
36
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
17
275
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
18 ## Getting Started
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
19
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
20 - Fork the module repository on GitHub and clone to your workspace
36
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
21
275
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
22 - Make your changes!
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
23
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
24 ## Commit Checklist
36
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
25
275
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
26 ### The Basics
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
27
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
28 - [x] my commit is a single logical unit of work
36
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
29
275
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
30 - [x] I have checked for unnecessary whitespace with "git diff --check"
36
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
31
275
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
32 - [x] my commit does not include commented out code or unneeded files
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
33
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
34 ### The Content
36
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
35
275
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
36 - [x] my commit includes tests for the bug I fixed or feature I added
36
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
37
275
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
38 - [x] my commit includes appropriate documentation changes if it is introducing a new feature or changing existing functionality
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
39
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
40 - [x] my code passes existing test suites
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
41
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
42 ### The Commit Message
36
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
43
275
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
44 - [x] the first line of my commit message includes:
36
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
45
275
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
46 - [x] an issue number (if applicable), e.g. "(MODULES-xxxx) This is the first line"
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
47
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
48 - [x] a short description (50 characters is the soft limit, excluding ticket number(s))
36
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
49
275
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
50 - [x] the body of my commit message:
36
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
51
275
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
52 - [x] is meaningful
36
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
53
275
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
54 - [x] uses the imperative, present tense: "change", not "changed" or "changes"
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
55
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
56 - [x] includes motivation for the change, and contrasts its implementation with the previous behavior
36
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
57
275
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
58 ## Submission
36
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
59
275
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
60 ### Pre-requisites
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
61
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
62 - Make sure you have a [GitHub account](https://github.com/join)
36
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
63
275
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
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.
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
65
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
66 ### Push and PR
36
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
67
275
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
68 - Push your changes to your fork
36
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
69
275
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
70 - [Open a Pull Request](https://help.github.com/articles/creating-a-pull-request-from-a-fork/) against the repository in the puppetlabs organization
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
71
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
72 ## More about commits
36
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
73
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
74 1. Make separate commits for logically separate changes.
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
75
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
76 Please break your commits down into logically consistent units
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
77 which include new or changed tests relevant to the rest of the
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
78 change. The goal of doing this is to make the diff easier to
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
79 read for whoever is reviewing your code. In general, the easier
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
80 your diff is to read, the more likely someone will be happy to
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
81 review it and get it into the code base.
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
82
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
83 If you are going to refactor a piece of code, please do so as a
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
84 separate commit from your feature or bug fix changes.
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
85
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
86 We also really appreciate changes that include tests to make
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
87 sure the bug is not re-introduced, and that the feature is not
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
88 accidentally broken.
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
89
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
90 Describe the technical detail of the change(s). If your
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
91 description starts to get too long, that is a good sign that you
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
92 probably need to split up your commit into more finely grained
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
93 pieces.
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
94
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
95 Commits which plainly describe the things which help
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
96 reviewers check the patch and future developers understand the
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
97 code are much more likely to be merged in with a minimum of
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
98 bike-shedding or requested changes. Ideally, the commit message
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
99 would include information, and be in a form suitable for
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
100 inclusion in the release notes for the version of Puppet that
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
101 includes them.
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
102
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
103 Please also check that you are not introducing any trailing
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
104 whitespace or other "whitespace errors". You can do this by
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
105 running "git diff --check" on your changes before you commit.
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
106
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
107 2. Sending your patches
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
108
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
109 To submit your changes via a GitHub pull request, we _highly_
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
110 recommend that you have them on a topic branch, instead of
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
111 directly on "master".
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
112 It makes things much easier to keep track of, especially if
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
113 you decide to work on another thing before your first change
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
114 is merged in.
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
115
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
116 GitHub has some pretty good
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
117 [general documentation](http://help.github.com/) on using
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
118 their site. They also have documentation on
275
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
119 [creating pull requests](https://help.github.com/articles/creating-a-pull-request-from-a-fork/).
36
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
120
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
121 In general, after pushing your topic branch up to your
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
122 repository on GitHub, you can switch to the branch in the
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
123 GitHub UI and click "Pull Request" towards the top of the page
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
124 in order to open a pull request.
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
125
275
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
126 3. Update the related JIRA issue.
36
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
127
275
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
128 If there is a JIRA issue associated with the change you
36
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
129 submitted, then you should update the ticket to include the
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
130 location of your branch, along with any other commentary you
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
131 may wish to make.
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
132
275
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
133 # Testing
36
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
134
275
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
135 ## Getting Started
36
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
136
275
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
137 Our Puppet modules provide [`Gemfile`](./Gemfile)s, which can tell a Ruby package manager such as [bundler](http://bundler.io/) what Ruby packages,
36
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
138 or Gems, are required to build, develop, and test this software.
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
139
275
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
140 Please make sure you have [bundler installed](http://bundler.io/#getting-started) on your system, and then use it to
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
141 install all dependencies needed for this project in the project root by running
36
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
142
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
143 ```shell
275
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
144 % bundle install --path .bundle/gems
36
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
145 Fetching gem metadata from https://rubygems.org/........
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
146 Fetching gem metadata from https://rubygems.org/..
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
147 Using rake (10.1.0)
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
148 Using builder (3.2.2)
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
149 -- 8><-- many more --><8 --
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
150 Using rspec-system-puppet (2.2.0)
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
151 Using serverspec (0.6.3)
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
152 Using rspec-system-serverspec (1.0.0)
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
153 Using bundler (1.3.5)
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
154 Your bundle is complete!
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
155 Use `bundle show [gemname]` to see where a bundled gem is installed.
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
156 ```
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
157
275
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
158 NOTE: some systems may require you to run this command with sudo.
36
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
159
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
160 If you already have those gems installed, make sure they are up-to-date:
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
161
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
162 ```shell
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
163 % bundle update
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
164 ```
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
165
275
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
166 ## Running Tests
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
167
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
168 With all dependencies in place and up-to-date, run the tests:
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
169
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
170 ### Unit Tests
36
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
171
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
172 ```shell
275
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
173 % bundle exec rake spec
36
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
174 ```
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
175
275
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
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.
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
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),
36
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
178 rspec tests define them in [.fixtures.yml](./fixtures.yml).
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
179
275
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
180 ### Acceptance Tests
36
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
181
275
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
182 Some Puppet modules also come with acceptance tests, which use [beaker][]. These tests spin up a virtual machine under
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
183 [VirtualBox](https://www.virtualbox.org/), controlled with [Vagrant](http://www.vagrantup.com/), to simulate scripted test
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
184 scenarios. In order to run these, you need both Virtualbox and Vagrant installed on your system.
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
185
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
186 Run the tests by issuing the following command
36
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
187
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
188 ```shell
275
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
189 % bundle exec rake spec_clean
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
190 % bundle exec rspec spec/acceptance
36
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
191 ```
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
192
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
193 This will now download a pre-fabricated image configured in the [default node-set](./spec/acceptance/nodesets/default.yml),
275
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
194 install Puppet, copy this module, and install its dependencies per [spec/spec_helper_acceptance.rb](./spec/spec_helper_acceptance.rb)
36
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
195 and then run all the tests under [spec/acceptance](./spec/acceptance).
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
196
275
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
197 ## Writing Tests
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
198
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
199 ### Unit Tests
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
200
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
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
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
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]
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
203 but here's a tiny sample:
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
204
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
205 Sample manifest:
36
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
206
275
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
207 ```puppet
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
208 file { "a test file":
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
209 ensure => present,
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
210 path => "/etc/sample",
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
211 }
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
212 ```
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
213
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
214 Sample test:
36
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
215
275
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
216 ```ruby
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
217 it 'does a thing' do
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
218 expect(subject).to contain_file("a test file").with({:path => "/etc/sample"})
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
219 end
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
220 ```
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
221
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
222 ### Acceptance Tests
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
223
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
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
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
225 twice to check for idempotency or errors, then run expectations.
36
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
226
275
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
227 ```ruby
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
228 it 'does an end-to-end thing' do
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
229 pp = <<-EOF
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
230 file { 'a test file':
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
231 ensure => present,
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
232 path => "/etc/sample",
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
233 content => "test string",
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
234 }
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
235
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
236 apply_manifest(pp, :catch_failures => true)
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
237 apply_manifest(pp, :catch_changes => true)
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
238
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
239 end
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
240
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
241 describe file("/etc/sample") do
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
242 it { is_expected.to contain "test string" }
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
243 end
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
244
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
245 ```
36
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
246
275
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
247 # If you have commit access to the repository
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
248
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
249 Even if you have commit access to the repository, you still need to go through the process above, and have someone else review and merge
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
250 in your changes. The rule is that **all changes must be reviewed by a project developer that did not write the code to ensure that
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
251 all changes go through a code review process.**
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
252
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
253 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.
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
254
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
255 # Get Help
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
256
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
257 ### On the web
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
258 * [Puppet help messageboard](http://puppet.com/community/get-help)
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
259 * [Writing tests](https://docs.puppet.com/guides/module_guides/bgtm.html#step-three-module-testing)
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
260 * [General GitHub documentation](http://help.github.com/)
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
261 * [GitHub pull request documentation](http://help.github.com/send-pull-requests/)
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
262
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
263 ### On chat
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
264 * Slack (slack.puppet.com) #forge-modules, #puppet-dev, #windows, #voxpupuli
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
265 * IRC (freenode) #puppet-dev, #voxpupuli
36
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
266
37675581a273 Update Puppet module for Apache (pulls in concat module)
IBBoard <dev@ibboard.co.uk>
parents:
diff changeset
267
275
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
268 [rspec-puppet]: http://rspec-puppet.com/
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
269 [rspec-puppet_docs]: http://rspec-puppet.com/documentation/
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
270 [beaker]: https://github.com/puppetlabs/beaker
d9352a684e62 Mass update of modules to remove deprecation warnings
IBBoard <dev@ibboard.co.uk>
parents: 36
diff changeset
271 [beaker-rspec]: https://github.com/puppetlabs/beaker-rspec