Mercurial > repos > other > Puppet

annotate modules/translate/CONTRIBUTING.md @ 335:aa9f570d6a9c

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