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 we can do better.
   4
   5 #### Table of Contents
   6 1. [Overview](#overview)
   7 1. [Communication](#communication)
   8     * [Issues](#issues)
   9     * [Gitter](#gitter)
  10 1. [Patches](#patches)
  11 1. [Testing](#testing)
  12     * [Test Dependencies](#test-dependencies)
  13     * [Syntax and Style Tests](#syntax-and-style-tests)
  14     * [Unit Tests](#unit-tests)
  15     * [System Tests](#system-tests)
  16
  17 ## Overview
  18
  19 We use [GitHub Issues](https://github.com/dfarrell07/puppet-opendaylight/issues) for most communication, including bug reports, feature requests and questions.
  20
  21 We accept patches via [GitHub Pull Requests](https://github.com/dfarrell07/puppet-opendaylight/pulls). Please fork our repo, make your changes, commit them to a feature branch and *submit a PR to have it merged back into this project*. We'll give feedback and get it merged ASAP.
  22
  23 ## Communication
  24
  25 Please use public, documented communication instead of reaching out to developers 1-1.
  26
  27 Open Source projects benefit from always communicating in the open. Other people may run into the same issue, search for a similar trace and find your question, already answered. More eyes may even get your question answered faster.
  28
  29 We prefer [Issues](https://github.com/dfarrell07/puppet-opendaylight/issues) for most communication.
  30
  31 ### Issues
  32
  33 Please use our [GitHub Issues](https://github.com/dfarrell07/puppet-opendaylight/issues) freely, even for small things! They are the primary method by which we track what's going on in the project.
  34
  35 The labels assigned to an issue can tell you important things about it.
  36
  37 For example, issues tagged [`good-for-beginners`](https://github.com/dfarrell07/puppet-opendaylight/labels/good-for-beginners) are likely to not require much background knowledge and be fairly self-contained, perfect for people new to the project who are looking to get involved.
  38
  39 The priority-related issue labels ([`prio:high`](https://github.com/dfarrell07/puppet-opendaylight/labels/prio%3Ahigh), [`piro:normal`](https://github.com/dfarrell07/puppet-opendaylight/labels/prio%3Anormal)...) are also important to note. They typically accurately reflect the next TODOs the community will complete.
  40
  41 The `info:progress` labels may not always be up-to-date, but will be used when appropriate (typically long-standing issues that take multiple commits).
  42
  43 Issues can be referenced and manipulated from git commit messages. Just referencing the issue's number (`#42`) will link the commit and issue. Issues can also be closed from commit messages with `closes #42` (and [a variety of other key words](https://help.github.com/articles/closing-issues-via-commit-messages/)).
  44
  45 ### Gitter
  46
  47 We're experimenting with Gitter, a GitHub-driven chat service that works on a per-repo basis.
  48
  49 Feel free to hop in [our room](https://gitter.im/dfarrell07/puppet-opendaylight) and test it out with us.
  50
  51 ## Patches
  52
  53 Please use [Pull Requests](https://github.com/dfarrell07/puppet-opendaylight/pulls) to submit patches.
  54
  55 Basics of a pull request:
  56 * Use the GitHub web UI to fork our repo.
  57 * Clone your fork to your local system.
  58 * Make your changes.
  59 * Commit your changes, using a good commit message and referencing any applicable issues.
  60 * Push your commit.
  61 * Submit a pull request against the project, again using GitHub's web UI.
  62 * We'll give feedback and get your changed merged ASAP.
  63 * You contributed! Thank you!
  64
  65 Other tips for submitting excellent pull requests:
  66 * If you'd like to make more than one logically distinct change, please submit them as different pull requests (if they don't depend on each other) or different commits in the same PR (if they do).
  67 * If your PR contains a number of commits that provide one logical change, please squash them using `git rebase`.
  68 * Please provide test coverage for your changes.
  69 * If applicable, please provide documentation updates to reflect your changes.
  70
  71 ## Testing
  72
  73 ### Test Dependencies
  74
  75 The testing tools have a number of dependencies. We use [Bundler](http://bundler.io/) to make installing them easy.
  76
  77 ```ShellSession
  78 [~/puppet-opendaylight]$ bundle install
  79 ```
  80
  81 ### Syntax and Style Tests
  82
  83 We use [Puppet Lint](http://puppet-lint.com/) and [Puppet Syntax](https://github.com/gds-operations/puppet-syntax) to validate the module's syntax and style.
  84
  85 ```ShellSession
  86 [~/puppet-opendaylight]$ bundle exec rake lint
  87 [~/puppet-opendaylight]$ bundle exec rake syntax
  88 ```
  89
  90 ### Unit Tests
  91
  92 We use rspec-puppet to provide unit test coverage.
  93
  94 To run the unit tests and generate a coverage report, use:
  95
  96 ```ShellSession
  97 [~/puppet-opendaylight]$ bundle exec rake spec
  98 # Snip test output
  99 Finished in 10.08 seconds (files took 0.50776 seconds to load)
 100 537 examples, 0 failures
 101
 102
 103 Total resources:   19
 104 Touched resources: 19
 105 Resource coverage: 100.00%
 106 ```
 107
 108 Note that we have a very large number of tests and 100% test coverage.
 109
 110 To run the syntax, style and unit tests in one rake task (recommended), use:
 111
 112 ```ShellSession
 113 [~/puppet-opendaylight]$ bundle exec rake test
 114 ```
 115
 116 ### System Tests
 117
 118 While the [unit tests](#unit-tests) are able to quickly find many errors, they don't do much more than checking that the code compiles to a given state. To verify that the Puppet module behaves as desired once applied to a real, running system, we use [Beaker](https://github.com/puppetlabs/beaker).
 119
 120 Beaker stands up virtual machines using Vagrant, applies the OpenDaylight puppet module with various combinations of params and uses [Serverspec](http://serverspec.org/resource_types.html) to validate the resulting system state.
 121
 122 To run our Beaker test against the primary target OS (CentOS 7) using the recommended RPM-based install method:
 123
 124 ```ShellSession
 125 [~/puppet-opendaylight]$ bundle exec rake beaker
 126 ```
 127
 128 The `RS_SET` environment variable can be use to change Beaker's target OS (Fedora 20, Fedora 21, CentOS 7, Ubuntu 14.04). ODL's install method (RPM or tarball) can be configured via the `INSTALL_METHOD` environment variable.
 129
 130 ```ShellSession
 131 [~/puppet-opendaylight]$ RS_SET=fedora-20 INSTALL_METHOD=tarball bundle exec rake beaker
 132 ```
 133
 134 There are a number of pre-defined rake tasks to simplify running common Beaker tests.
 135
 136 ```ShellSession
 137 [~/puppet-opendaylight]$ bundle exec rake centos
 138 [~/puppet-opendaylight]$ bundle exec rake centos_tarball
 139 [~/puppet-opendaylight]$ bundle exec rake fedora_20
 140 [~/puppet-opendaylight]$ bundle exec rake fedora_21
 141 [~/puppet-opendaylight]$ bundle exec rake ubuntu
 142 ```
 143
 144 If you'd like to preserve the Beaker VM after a test run, perhaps for manual inspection or a quicker follow-up test run, use the `BEAKER_DESTROY` environment variable.
 145
 146 ```ShellSession
 147 [~/puppet-opendaylight]$ BEAKER_DESTROY=no bundle exec rake centos
 148 ```
 149
 150 For more information about using Beaker, see [these docs](https://github.com/puppetlabs/beaker/wiki/How-to-Write-a-Beaker-Test-for-a-Module#typical-workflow).
 151
 152 ### Tests in Continuous Integration
 153
 154 We use [Travis CI](https://travis-ci.org/dfarrell07/puppet-opendaylight) to run our unit, syntax and style tests against a matrix of supported Ruby and Puppet versions at every commit. This currently results in >8500 automated tests per commit.