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
  12 ## Overview
  13
  14 We use [GitHub Issues](https://github.com/dfarrell07/puppet-opendaylight/issues) for most communication, including bug reports, feature requests and questions.
  15
  16 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.
  17
  18 ## Communication
  19
  20 Please use public, documented communication instead of reaching out to developers 1-1.
  21
  22 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.
  23
  24 We prefer [Issues](https://github.com/dfarrell07/puppet-opendaylight/issues) for most communication.
  25
  26 ### Issues
  27
  28 Please use our [GitHub Issues freely](https://github.com/dfarrell07/puppet-opendaylight/issues), even for small things! They are the primary method by which we track what's going on in the project.
  29
  30 The lables assigned to an issue can tell you important things about it.
  31
  32 For example, issues tagged `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.
  33
  34 The priority-related issue labels (`prio:high`, `piro:normal`...) are also important to note. They typically accurately reflect the next TODOs the community will complete.
  35
  36 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).
  37
  38 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/)).
  39
  40 ### Gitter
  41
  42 We're experimenting with Gitter, a GitHub-driven chat service that works on a per-repo basis.
  43
  44 Feel free to hop in [our room](https://gitter.im/dfarrell07/puppet-opendaylight) and test it out with us.
  45
  46 ## Patches
  47
  48 Please use [Pull Requests](https://github.com/dfarrell07/puppet-opendaylight/pulls) to submit patches.
  49
  50 Basics of a pull request:
  51 * Use the GitHub web UI to fork our repo
  52 * Clone your fork to your local system
  53 * Make your changes
  54 * Commit your changes, using a good commit message and referencing any applicable issues
  55 * Push your commit
  56 * Submit a pull request against the project, again using GitHub's web UI
  57 * We'll give feedback and get your changed merged ASAP.
  58 * You contributed! Thank you!
  59
  60 ## Testing
  61
  62 ### Dependencies
  63
  64 The testing and development tools have a bunch of dependencies,
  65 all managed by [Bundler](http://bundler.io/) according to the
  66 [Puppet support matrix](http://docs.puppetlabs.com/guides/platforms.html#ruby-versions).
  67
  68 By default the tests use a baseline version of Puppet.
  69
  70 If you have Ruby 2.x or want a specific version of Puppet,
  71 you must set an environment variable such as:
  72
  73     export PUPPET_VERSION="~> 3.2.0"
  74
  75 Install the dependencies like so...
  76
  77     bundle install
  78
  79 ### Syntax and style
  80
  81 The test suite will run [Puppet Lint](http://puppet-lint.com/) and
  82 [Puppet Syntax](https://github.com/gds-operations/puppet-syntax) to
  83 check various syntax and style things. You can run these locally with:
  84
  85     bundle exec rake lint
  86     bundle exec rake syntax
  87
  88 ### Running the unit tests
  89
  90 The unit test suite covers most of the code. As mentioned above, please
  91 add tests if you're adding new functionality. Running the test suite is done
  92 with:
  93
  94     bundle exec rake spec
  95
  96 Note also you can run the syntax, style and unit tests in one go with:
  97
  98     bundle exec rake test
  99
 100 #### Automatically run the tests
 101
 102 During development of your puppet module you might want to run your unit
 103 tests a couple of times. You can use the following command to automate
 104 running the unit tests on every change made in the manifests folder.
 105
 106     bundle exec guard
 107
 108 ### Integration tests
 109
 110 The unit tests just check the code runs, not that it does exactly what
 111 we want on a real machine. For that we're using
 112 [Beaker](https://github.com/puppetlabs/beaker).
 113
 114 Beaker fires up a new virtual machine (using Vagrant) and runs a series of
 115 simple tests against it after applying the module. You can run our Beaker
 116 tests with:
 117
 118     bundle exec rake acceptance
 119
 120 This will use the host described in `spec/acceptance/nodeset/default.yml`
 121 by default. To run against another host, set the `RS_SET` environment
 122 variable to the name of a host described by a `.yml` file in the
 123 `nodeset` directory. For example, to run against Fedora 20:
 124
 125     RS_SET=fedora-20-x64 bundle exec rake acceptance
 126
 127 If you don't want to have to recreate the virtual machine every time you
 128 can use `BEAKER_DESTROY=no` and `BEAKER_PROVISION=no`. On the first run you will
 129 at least need `BEAKER_PROVISION` set to yes (the default). The Vagrantfile
 130 for the created virtual machines will be in `.vagrant/beaker_vagrant_files`.