CONTRIBUTING.markdown

   1 # Contributing to the OpenDaylight Puppet Module
   2
   3 We work to make contributing easy. Please let us know if you spot something
   4 we can do better.
   5
   6 #### Table of Contents
   7
   8 1. [Overview](#overview)
   9 2. [Communication](#communication)
  10    - [Issues](#issues)
  11    - [IRC channel](#irc-channel)
  12 3. [Patches](#patches)
  13 4. [Testing](#testing)
  14    - [Test Dependencies](#test-dependencies)
  15    - [Syntax and Style Tests](#syntax-and-style-tests)
  16    - [Unit Tests](#unit-tests)
  17    - [System Tests](#system-tests)
  18    - [Tests in Continuous Integration](#tests-in-continuous-integration)
  19
  20 ## Overview
  21
  22 We use [GitHub Issues][1] for most communication, including bug reports,
  23 feature requests and questions.
  24
  25 We accept patches via [GitHub Pull Requests][2]. Please fork our repo,
  26 make your changes, commit them to a feature branch and *submit a PR to
  27 have it merged back into this project*. We'll give feedback and get it
  28 merged ASAP.
  29
  30 ## Communication
  31
  32 *Please use public, documented communication instead of reaching out to
  33 developers 1-1.*
  34
  35 Open Source projects benefit from always communicating in the open. Previously
  36 answered questions end up becoming documentation for other people hitting
  37 similar issues. More eyes may get your question answered faster. Doing
  38 everything in the open keeps community members on an equal playing field
  39 (`@<respected company>` email addresses don't get priority, good questions do).
  40
  41 We prefer [Issues][1] for most communication.
  42
  43 ### Issues
  44
  45 Please use our [GitHub Issues][1] freely, even for small things! They are the
  46 primary method by which we track what's going on in the project.
  47
  48 The labels assigned to an issue can tell you important things about it.
  49
  50 For example, issues tagged [`good-for-beginners`][3] are likely to not require
  51 much background knowledge and be fairly self-contained, perfect for people new
  52 to the project who are looking to get involved.
  53
  54 The priority-related issue labels ([`prio:high`][4], [`piro:normal`][5]...)
  55 are also important to note. They typically accurately reflect the next TODOs
  56 the community will complete.
  57
  58 The `info:progress` labels may not always be up-to-date, but will be used when
  59 appropriate (typically long-standing issues that take multiple commits).
  60
  61 Issues can be referenced and manipulated from git commit messages. Just
  62 referencing the issue's number (`#42`) will link the commit and issue. Issues
  63 can also be closed from commit messages with `closes #42` (and [a variety
  64 of other key words][6]).
  65
  66 ### IRC channel
  67
  68 Feel free to join us at **#opendaylight-integration** on `chat.freenode.net`.
  69 You can also use web client for Freenode to join us at [webchat][19].
  70
  71 ## Patches
  72
  73 Please use [Pull Requests][2] to submit patches.
  74
  75 Basics of a pull request:
  76
  77 - Use the GitHub web UI to fork our repo.
  78 - Clone your fork to your local system.
  79 - Make your changes.
  80 - Commit your changes, using a [good commit message][7] and referencing any
  81   applicable issues.
  82 - Push your commit.
  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][8]!
  86
  87 Other tips for submitting excellent pull requests:
  88
  89 - If you'd like to make more than one logically distinct change, please submit
  90   them as different pull requests (if they don't depend on each other) or
  91   different commits in the same PR (if they do).
  92 - If your PR contains a number of commits that provide one logical change,
  93   please squash them using `git rebase`.
  94 - Please provide test coverage for your changes.
  95 - If applicable, please provide documentation updates to reflect your changes.
  96
  97 ## Testing
  98
  99 ### Test Dependencies
 100
 101 The testing tools have a number of dependencies. We use [Bundler][9] to make
 102 installing them easy.
 103
 104 ```
 105 $ sudo yum install -y rubygems ruby-devel gcc-c++ zlib-devel patch \
 106     redhat-rpm-config make
 107 $ gem install bundler
 108 $ bundle install
 109 $ bundle update
 110 ```
 111
 112 ### Syntax and Style Tests
 113
 114 We use [Puppet Lint][10], [Puppet Syntax][11] and [metadata-json-lint][12] to
 115 validate the module's syntax and style.
 116
 117 ```
 118 $ bundle exec rake lint
 119 $ bundle exec rake syntax
 120 $ bundle exec rake metadata
 121 ```
 122
 123 ### Unit Tests
 124
 125 We use rspec-puppet to provide unit test coverage.
 126
 127 To run the unit tests and generate a coverage report, use:
 128
 129 ```
 130 $ bundle exec rake spec
 131 # Snip test output
 132 Finished in 10.08 seconds (files took 0.50776 seconds to load)
 133 537 examples, 0 failures
 134
 135
 136 Total resources:   19
 137 Touched resources: 19
 138 Resource coverage: 100.00%
 139 ```
 140
 141 Note that we have a very large number of tests and 100% test coverage.
 142
 143 To run the syntax, style and unit tests in one rake task (recommended), use:
 144
 145 ```
 146 $ bundle exec rake test
 147 ```
 148
 149 ### System Tests
 150
 151 While the [unit tests](#unit-tests) are able to quickly find many errors,
 152 they don't do much more than checking that the code compiles to a given state.
 153 To verify that the Puppet module behaves as desired once applied to a real,
 154 running system, we use [Beaker][13].
 155
 156 Beaker stands up virtual machines or containers using Vagrant or Docker,
 157 applies the OpenDaylight Puppet module with various combinations of params
 158 and uses [Serverspec][14] to validate the resulting system state.
 159
 160 Beaker depends on Vagrant ([Vagrant downloads page][17]) for managing VMs,
 161 which in turn depends on VirtualBox ([VirtualBox downloads page][18]) and
 162 the `kmod-VirtualBox` package.
 163
 164 Beaker depends on [Docker][20] for managing containers.
 165
 166 To run Beaker tests against CentOS 7 in a VM using the latest OpenDaylight
 167 Carbon RPM, use:
 168
 169 ```
 170 $ bundle exec rake cent_6test_vm
 171 ```
 172
 173 To do the same tests in a CentOS container:
 174
 175 ```
 176 $ bundle exec rake cent_6test_dock
 177 ```
 178
 179 To run VM or container-based tests for all OSs:
 180
 181 ```
 182 $ bundle exec rake acceptance_vm
 183 $ bundle exec rake acceptance_dock
 184 ```
 185
 186 If you'd like to preserve the Beaker VM after a test run, perhaps for manual
 187 inspection or a quicker follow-up test run, use the `BEAKER_destroy`
 188 environment variable.
 189
 190 ```
 191 $ BEAKER_destroy=no bundle exec rake centos
 192 ```
 193
 194 You can then connect to the VM by navigating to the directory that contains
 195 its Vagrantfile and using standard Vagrant commands.
 196
 197 ```
 198 $ cd .vagrant/beaker_vagrant_files/centos-7.yml
 199 $ vagrant status
 200 Current machine states:
 201
 202 centos-7                  running (virtualbox)
 203 $ vagrant ssh
 204 $ sudo systemctl is-active opendaylight
 205 active
 206 $ logout
 207 $ vagrant destroy -f
 208 ```
 209
 210 For more information about using Beaker, see [these docs][15].
 211
 212 ### Tests in Continuous Integration
 213
 214 We use [Travis CI][16] 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.
 217
 218 [1]: https://github.com/dfarrell07/puppet-opendaylight/issues
 219
 220 [2]: https://github.com/dfarrell07/puppet-opendaylight/pulls
 221
 222 [3]: https://github.com/dfarrell07/puppet-opendaylight/labels/good-for-beginners
 223
 224 [4]: https://github.com/dfarrell07/puppet-opendaylight/labels/prio%3Ahigh
 225
 226 [5]: https://github.com/dfarrell07/puppet-opendaylight/labels/prio%3Anormal
 227
 228 [6]: https://help.github.com/articles/closing-issues-via-commit-messages/
 229
 230 [7]: http://chris.beams.io/posts/git-commit/
 231
 232 [8]: http://cdn3.volusion.com/74gtv.tjme9/v/vspfiles/photos/Delicious%20Dozen-1.jpg
 233
 234 [9]: http://bundler.io/
 235
 236 [10]: http://puppet-lint.com/
 237
 238 [11]: https://github.com/gds-operations/puppet-syntax
 239
 240 [12]: https://github.com/puppet-community/metadata-json-lint
 241
 242 [13]: https://github.com/puppetlabs/beaker
 243
 244 [14]: http://serverspec.org/resource_types.html
 245
 246 [15]: https://github.com/puppetlabs/beaker/wiki/How-to-Write-a-Beaker-Test-for-a-Module#typical-workflow
 247
 248 [16]: https://travis-ci.org/dfarrell07/puppet-opendaylight
 249
 250 [17]: https://www.vagrantup.com/downloads.html
 251
 252 [18]: www.virtualbox.org/wiki/Linux_Downloads
 253
 254 [19]: http://webchat.freenode.net/?channels=opendaylight-integration
 255
 256 [20]: https://docs.docker.com/engine/installation/