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 1. [Overview](#overview)
   8 1. [Communication](#communication)
   9     * [Issues](#issues)
  10     * [Gitter](#gitter)
  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)
  18
  19 ## Overview
  20
  21 We use [GitHub Issues][1] for most communication, including bug reports,
  22 feature requests and questions.
  23
  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
  27 merged ASAP.
  28
  29 ## Communication
  30
  31 *Please use public, documented communication instead of reaching out to
  32 developers 1-1.*
  33
  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).
  39
  40 We prefer [Issues][1] for most communication.
  41
  42 ### Issues
  43
  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.
  46
  47 The labels assigned to an issue can tell you important things about it.
  48
  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.
  52
  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.
  56
  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).
  59
  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]).
  64
  65 ### Gitter
  66
  67 We're experimenting with Gitter, a GitHub-driven chat service that works on a
  68 per-repo basis.
  69
  70 Feel free to hop in [our room][7] and test it out with us.
  71
  72 ## Patches
  73
  74 Please use [Pull Requests][2] to submit patches.
  75
  76 Basics of a pull request:
  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][8] 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][9]!
  86
  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.
  95
  96 ## Testing
  97
  98 ### Test Dependencies
  99
 100 The testing tools have a number of dependencies. We use [Bundler][10] to make
 101 installing them easy.
 102
 103 ```
 104 [~/puppet-opendaylight]$ yum install -y rubygems ruby-devel gcc-c++ zlib-devel patch
 105 [~/puppet-opendaylight]$ gem install bundler
 106 [~/puppet-opendaylight]$ bundle install
 107 ```
 108
 109 ### Syntax and Style Tests
 110
 111 We use [Puppet Lint][11], [Puppet Syntax][12] and [metadata-json-lint][13] to
 112 validate the module's syntax and style.
 113
 114 ```
 115 [~/puppet-opendaylight]$ bundle exec rake lint
 116 [~/puppet-opendaylight]$ bundle exec rake syntax
 117 [~/puppet-opendaylight]$ bundle exec rake metadata
 118 ```
 119
 120 ### Unit Tests
 121
 122 We use rspec-puppet to provide unit test coverage.
 123
 124 To run the unit tests and generate a coverage report, use:
 125
 126 ```
 127 [~/puppet-opendaylight]$ bundle exec rake spec
 128 # Snip test output
 129 Finished in 10.08 seconds (files took 0.50776 seconds to load)
 130 537 examples, 0 failures
 131
 132
 133 Total resources:   19
 134 Touched resources: 19
 135 Resource coverage: 100.00%
 136 ```
 137
 138 Note that we have a very large number of tests and 100% test coverage.
 139
 140 To run the syntax, style and unit tests in one rake task (recommended), use:
 141
 142 ```
 143 [~/puppet-opendaylight]$ bundle exec rake test
 144 ```
 145
 146 ### System Tests
 147
 148 While the [unit tests](#unit-tests) are able to quickly find many errors,
 149 they don't do much more than checking that the code compiles to a given state.
 150 To verify that the Puppet module behaves as desired once applied to a real,
 151 running system, we use [Beaker][14].
 152
 153 Beaker stands up virtual machines using Vagrant, applies the OpenDaylight
 154 Puppet module with various combinations of params and uses [Serverspec][15]
 155 to validate the resulting system state.
 156
 157 Beaker depends on Vagrant ([Vagrant downloads page][18]) for managing VMs,
 158 which in turn depends on VirtualBox ([VirtualBox downloads page][19]) and
 159 the `kmod-VirtualBox` package.
 160
 161 To run our Beaker tests against the primary target OS (CentOS 7) using the
 162 recommended RPM-based install method, use:
 163
 164 ```
 165 [~/puppet-opendaylight]$ bundle exec rake centos
 166 ```
 167
 168 There are a number of pre-defined rake tasks to simplify running common
 169 Beaker tests.
 170
 171 ```
 172 [~/puppet-opendaylight]$ bundle exec rake centos
 173 [~/puppet-opendaylight]$ bundle exec rake centos_tarball
 174 [~/puppet-opendaylight]$ bundle exec rake fedora_20
 175 [~/puppet-opendaylight]$ bundle exec rake fedora_21
 176 [~/puppet-opendaylight]$ bundle exec rake ubuntu
 177 ```
 178
 179 If you'd like to preserve the Beaker VM after a test run, perhaps for manual
 180 inspection or a quicker follow-up test run, use the `BEAKER_destroy`
 181 environment variable.
 182
 183 ```
 184 [~/puppet-opendaylight]$ BEAKER_destroy=no bundle exec rake centos
 185 ```
 186
 187 You can then connect to the VM by navigating to the directory that contains
 188 its Vagrantfile and using standard Vagrant commands.
 189
 190 ```
 191 [~/puppet-opendaylight]$ cd .vagrant/beaker_vagrant_files/centos-7.yml
 192 [~/puppet-opendaylight/.vagrant/beaker_vagrant_files/centos-7.yml]$ vagrant status
 193 Current machine states:
 194
 195 centos-7                  running (virtualbox)
 196 [~/puppet-opendaylight/.vagrant/beaker_vagrant_files/centos-7.yml]$ vagrant ssh
 197 [vagrant@centos-7 ~]$ sudo systemctl status opendaylight
 198 opendaylight.service - OpenDaylight SDN Controller
 199    Loaded: loaded (/usr/lib/systemd/system/opendaylight.service; enabled)
 200    Active: active (running) since Fri 2015-04-24 16:34:07 UTC; 1min 1s ago
 201      Docs: https://wiki.opendaylight.org/view/Main_Page
 202            http://www.opendaylight.org/
 203 [vagrant@centos-7 ~]$ logout
 204 [~/puppet-opendaylight/.vagrant/beaker_vagrant_files/centos-7.yml]$ vagrant destroy -f
 205 ```
 206
 207 For more information about using Beaker, see [these docs][16].
 208
 209 ### Tests in Continuous Integration
 210
 211 We use [Travis CI][17] to run our unit, syntax and style tests against a
 212 matrix of supported Ruby and Puppet versions at every commit. This currently
 213 results in >8500 automated tests per commit.
 214
 215
 216 [1]: https://github.com/dfarrell07/puppet-opendaylight/issues
 217 [2]: https://github.com/dfarrell07/puppet-opendaylight/pulls
 218 [3]: https://github.com/dfarrell07/puppet-opendaylight/labels/good-for-beginners
 219 [4]: https://github.com/dfarrell07/puppet-opendaylight/labels/prio%3Ahigh
 220 [5]: https://github.com/dfarrell07/puppet-opendaylight/labels/prio%3Anormal
 221 [6]: https://help.github.com/articles/closing-issues-via-commit-messages/
 222 [7]: https://gitter.im/dfarrell07/puppet-opendaylight
 223 [8]: http://chris.beams.io/posts/git-commit/
 224 [9]: http://cdn3.volusion.com/74gtv.tjme9/v/vspfiles/photos/Delicious%20Dozen-1.jpg
 225 [10]: http://bundler.io/
 226 [11]: http://puppet-lint.com/
 227 [12]: https://github.com/gds-operations/puppet-syntax
 228 [13]: https://github.com/puppet-community/metadata-json-lint
 229 [14]: https://github.com/puppetlabs/beaker
 230 [15]: http://serverspec.org/resource_types.html
 231 [16]: https://github.com/puppetlabs/beaker/wiki/How-to-Write-a-Beaker-Test-for-a-Module#typical-workflow
 232 [17]: https://travis-ci.org/dfarrell07/puppet-opendaylight
 233 [18]: https://www.vagrantup.com/downloads.html
 234 [19]: www.virtualbox.org/wiki/Linux_Downloads