1 # Contributing to the OpenDaylight Puppet Module
3 We work to make contributing easy. Please let us know if you spot something
7 1. [Overview](#overview)
8 1. [Communication](#communication)
11 1. [Patches](#patches)
12 1. [Testing](#testing)
13 * [Test Dependencies](#test-dependencies)
14 * [Syntax and Style Tests](#syntax-and-style-tests)
15 * [Unit Tests](#unit-tests)
16 * [System Tests](#system-tests)
17 * [Tests in Continuous Integration](#tests-in-continuous-integration)
21 We use [GitHub Issues][1] for most communication, including bug reports,
22 feature requests and questions.
24 We accept patches via [GitHub Pull Requests][2]. Please fork our repo,
25 make your changes, commit them to a feature branch and *submit a PR to
26 have it merged back into this project*. We'll give feedback and get it
31 *Please use public, documented communication instead of reaching out to
34 Open Source projects benefit from always communicating in the open. Previously
35 answered questions end up becoming documentation for other people hitting
36 similar issues. More eyes may get your question answered faster. Doing
37 everything in the open keeps community members on an equal playing field
38 (`@<respected company>` email addresses don't get priority, good questions do).
40 We prefer [Issues][1] for most communication.
44 Please use our [GitHub Issues][1] freely, even for small things! They are the
45 primary method by which we track what's going on in the project.
47 The labels assigned to an issue can tell you important things about it.
49 For example, issues tagged [`good-for-beginners`][3] are likely to not require
50 much background knowledge and be fairly self-contained, perfect for people new
51 to the project who are looking to get involved.
53 The priority-related issue labels ([`prio:high`][4], [`piro:normal`][5]...)
54 are also important to note. They typically accurately reflect the next TODOs
55 the community will complete.
57 The `info:progress` labels may not always be up-to-date, but will be used when
58 appropriate (typically long-standing issues that take multiple commits).
60 Issues can be referenced and manipulated from git commit messages. Just
61 referencing the issue's number (`#42`) will link the commit and issue. Issues
62 can also be closed from commit messages with `closes #42` (and [a variety
63 of other key words][6]).
67 We're experimenting with Gitter, a GitHub-driven chat service that works on a
70 Feel free to hop in [our room][7] and test it out with us.
74 Please use [Pull Requests][2] to submit patches.
76 Basics of a pull request:
77 * Use the GitHub web UI to fork our repo.
78 * Clone your fork to your local system.
80 * Commit your changes, using a [good commit message][8] and referencing any
83 * Submit a pull request against the project, again using GitHub's web UI.
84 * We'll give feedback and get your changed merged ASAP.
85 * You contributed! [Thank you][9]!
87 Other tips for submitting excellent pull requests:
88 * If you'd like to make more than one logically distinct change, please submit
89 them as different pull requests (if they don't depend on each other) or
90 different commits in the same PR (if they do).
91 * If your PR contains a number of commits that provide one logical change,
92 please squash them using `git rebase`.
93 * Please provide test coverage for your changes.
94 * If applicable, please provide documentation updates to reflect your changes.
100 The testing tools have a number of dependencies. We use [Bundler][10] to make
101 installing them easy.
104 [~/puppet-opendaylight]$ sudo yum install -y rubygems ruby-devel gcc-c++ zlib-devel \
105 patch redhat-rpm-config make
106 [~/puppet-opendaylight]$ gem install bundler
107 [~/puppet-opendaylight]$ bundle install
108 [~/puppet-opendaylight]$ bundle update
111 ### Syntax and Style Tests
113 We use [Puppet Lint][11], [Puppet Syntax][12] and [metadata-json-lint][13] to
114 validate the module's syntax and style.
117 [~/puppet-opendaylight]$ bundle exec rake lint
118 [~/puppet-opendaylight]$ bundle exec rake syntax
119 [~/puppet-opendaylight]$ bundle exec rake metadata
124 We use rspec-puppet to provide unit test coverage.
126 To run the unit tests and generate a coverage report, use:
129 [~/puppet-opendaylight]$ bundle exec rake spec
131 Finished in 10.08 seconds (files took 0.50776 seconds to load)
132 537 examples, 0 failures
136 Touched resources: 19
137 Resource coverage: 100.00%
140 Note that we have a very large number of tests and 100% test coverage.
142 To run the syntax, style and unit tests in one rake task (recommended), use:
145 [~/puppet-opendaylight]$ bundle exec rake test
150 While the [unit tests](#unit-tests) are able to quickly find many errors,
151 they don't do much more than checking that the code compiles to a given state.
152 To verify that the Puppet module behaves as desired once applied to a real,
153 running system, we use [Beaker][14].
155 Beaker stands up virtual machines using Vagrant, applies the OpenDaylight
156 Puppet module with various combinations of params and uses [Serverspec][15]
157 to validate the resulting system state.
159 Beaker depends on Vagrant ([Vagrant downloads page][18]) for managing VMs,
160 which in turn depends on VirtualBox ([VirtualBox downloads page][19]) and
161 the `kmod-VirtualBox` package.
163 To run our Beaker tests against the primary target OS (CentOS 7) using the
164 recommended RPM-based install method, use:
167 [~/puppet-opendaylight]$ bundle exec rake centos
170 There are a number of pre-defined rake tasks to simplify running common
174 [~/puppet-opendaylight]$ bundle exec rake centos_7_docker
175 [~/puppet-opendaylight]$ bundle exec rake centos
176 [~/puppet-opendaylight]$ bundle exec rake centos_tarball
177 [~/puppet-opendaylight]$ bundle exec rake fedora_22
178 [~/puppet-opendaylight]$ bundle exec rake ubuntu_1404
179 [~/puppet-opendaylight]$ bundle exec rake ubuntu_1404_docker
182 If you'd like to preserve the Beaker VM after a test run, perhaps for manual
183 inspection or a quicker follow-up test run, use the `BEAKER_destroy`
184 environment variable.
187 [~/puppet-opendaylight]$ BEAKER_destroy=no bundle exec rake centos
190 You can then connect to the VM by navigating to the directory that contains
191 its Vagrantfile and using standard Vagrant commands.
194 [~/puppet-opendaylight]$ cd .vagrant/beaker_vagrant_files/centos-7.yml
195 [~/puppet-opendaylight/.vagrant/beaker_vagrant_files/centos-7.yml]$ vagrant status
196 Current machine states:
198 centos-7 running (virtualbox)
199 [~/puppet-opendaylight/.vagrant/beaker_vagrant_files/centos-7.yml]$ vagrant ssh
200 [vagrant@centos-7 ~]$ sudo systemctl status opendaylight
201 opendaylight.service - OpenDaylight SDN Controller
202 Loaded: loaded (/usr/lib/systemd/system/opendaylight.service; enabled)
203 Active: active (running) since Fri 2015-04-24 16:34:07 UTC; 1min 1s ago
204 Docs: https://wiki.opendaylight.org/view/Main_Page
205 http://www.opendaylight.org/
206 [vagrant@centos-7 ~]$ logout
207 [~/puppet-opendaylight/.vagrant/beaker_vagrant_files/centos-7.yml]$ vagrant destroy -f
210 For more information about using Beaker, see [these docs][16].
212 ### Tests in Continuous Integration
214 We use [Travis CI][17] to run our unit, syntax and style tests against a
215 matrix of supported Ruby and Puppet versions at every commit. This currently
216 results in >8500 automated tests per commit.
219 [1]: https://github.com/dfarrell07/puppet-opendaylight/issues
220 [2]: https://github.com/dfarrell07/puppet-opendaylight/pulls
221 [3]: https://github.com/dfarrell07/puppet-opendaylight/labels/good-for-beginners
222 [4]: https://github.com/dfarrell07/puppet-opendaylight/labels/prio%3Ahigh
223 [5]: https://github.com/dfarrell07/puppet-opendaylight/labels/prio%3Anormal
224 [6]: https://help.github.com/articles/closing-issues-via-commit-messages/
225 [7]: https://gitter.im/dfarrell07/puppet-opendaylight
226 [8]: http://chris.beams.io/posts/git-commit/
227 [9]: http://cdn3.volusion.com/74gtv.tjme9/v/vspfiles/photos/Delicious%20Dozen-1.jpg
228 [10]: http://bundler.io/
229 [11]: http://puppet-lint.com/
230 [12]: https://github.com/gds-operations/puppet-syntax
231 [13]: https://github.com/puppet-community/metadata-json-lint
232 [14]: https://github.com/puppetlabs/beaker
233 [15]: http://serverspec.org/resource_types.html
234 [16]: https://github.com/puppetlabs/beaker/wiki/How-to-Write-a-Beaker-Test-for-a-Module#typical-workflow
235 [17]: https://travis-ci.org/dfarrell07/puppet-opendaylight
236 [18]: https://www.vagrantup.com/downloads.html
237 [19]: www.virtualbox.org/wiki/Linux_Downloads