# Contributing to the OpenDaylight Puppet Module
-We work to make contributing easy. Please let us know if you spot something we can do better.
+We work to make contributing easy. Please let us know if you spot something
+we can do better.
#### Table of Contents
+
1. [Overview](#overview)
-1. [Communication](#communication)
- * [Issues](#issues)
- * [Gitter](#gitter)
-1. [Patches](#patches)
+2. [Communication](#communication)
+ - [Trello](#trello)
+ - [Email](#email)
+ - [IRC](#irc)
+3. [Patches](#patches)
+4. [Testing](#testing)
+ - [Test Dependencies](#test-dependencies)
+ - [Coala Linting](#coala-linting)
+ - [Syntax and Style Tests](#syntax-and-style-tests)
+ - [Unit Tests](#unit-tests)
+ - [System Tests](#system-tests)
+ - [Tests in Continuous Integration](#tests-in-continuous-integration)
## Overview
-We use [GitHub Issues](https://github.com/dfarrell07/puppet-opendaylight/issues) for most communication, including bug reports, feature requests and questions.
+This is an offical upstream OpenDaylight codebase under the
+[Integration/Packaging project][1].
-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.
+We use [Trello][2] to track TODOs and [Gerrit][3] to submit changes. Email
+the [integration-dev mailing list][4] to get in touch.
## Communication
-Please use public, documented communication instead of reaching out to developers 1-1.
+### Trello
-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.
+Enhancements, bugs and such are tracked on [Trello][2]. The Trello board is
+shared with other Integration projects and related efforts. Puppet-opendaylight
+is under the scope of the Integration/Packaging project, which has a column
+and [tag][5] to collect its cards. Cards related to puppet-opendaylight will
+typically mention it by name in the title.
-We prefer [Issues](https://github.com/dfarrell07/puppet-opendaylight/issues) for most communication.
+### Email
-### Issues
+Please use the [integration-dev][4] mailing list to contact puppet-opendaylight
+developers. Please don't reach out to developers directly, per open source best
+practices.
-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.
+### IRC
-The lables assigned to an issue can tell you important things about it.
+To chat synchronously with developers, join the **#opendaylight-integration**
+on `chat.freenode.net`. If you're not familar with IRC, there are [web
+clients][6] that can make getting started easy.
-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.
+## Patches
-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.
+Please use [Gerrit][3] to submit patches. See the [ODL Gerrit docs][7]
+general getting-started help.
-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).
+Other tips for submitting excellent patches:
-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/)).
+- Please provide test coverage for your changes.
+- If applicable, please provide documentation updates to reflect your changes.
-### Gitter
+## Testing
-We're experimenting with Gitter, a GitHub-driven chat service that works on a per-repo basis.
+### Test Dependencies
-Feel free to hop in [our room](https://gitter.im/dfarrell07/puppet-opendaylight) and test it out with us.
+A Vagrant environment is provided to help manage test dependencies. All
+software prerequisites and configuration for running all types of tests
+should be handled automatically.
-## Patches
+To provision and connect to a Fedora-based VM with test tools installed:
-Please use [Pull Requests](https://github.com/dfarrell07/puppet-opendaylight/pulls) to submit patches.
+```
+$ vagrant up fedora
+$ vagrant ssh fedora
+# cd to ~/puppet-opendaylight and hack away
+```
-Basics of a pull request:
-* Use the GitHub web UI to fork our repo
-* Clone your fork to your local system
-* Make your changes
-* Commit your changes, using a good commit message and referencing any applicable issues
-* Push your commit
-* Submit a pull request against the project, again using GitHub's web UI
-* We'll give feedback and get your changed merged ASAP.
-* You contributed! Thank you!
+A CentOS-based VM is also provided.
-## Testing
+### Coala Linting
+
+We use Coala (manged by tox) to run various linters, like spacing, line
+length, Markdown, YAML, JSON, etc.
+
+```
+$ tox
+```
+
+### Syntax and Style Tests
+
+We use [Puppet Lint][8], [Puppet Syntax][9] and [metadata-json-lint][10] to
+validate the module's syntax and style.
+
+```
+$ bundle exec rake lint
+$ bundle exec rake syntax
+$ bundle exec rake metadata_lint
+```
+
+### Unit Tests
+
+We use rspec-puppet to provide unit test coverage.
+
+To run the unit tests and generate a coverage report, use:
+
+```
+$ bundle exec rake spec
+```
+
+To run the syntax, style and unit tests in one rake task (recommended), use:
+
+```
+$ bundle exec rake test
+```
+
+### System Tests
+
+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][11].
+
+Beaker stands up virtual machines or containers using Vagrant or Docker,
+applies the OpenDaylight Puppet module with various combinations of params
+and uses [Serverspec][12] to validate the resulting system state.
+
+To run Beaker tests against CentOS 7 in a VM using the latest OpenDaylight
+Carbon RPM, use:
-### Dependencies
+```
+$ bundle exec rake cent_6test_vm
+```
-The testing and development tools have a bunch of dependencies,
-all managed by [Bundler](http://bundler.io/) according to the
-[Puppet support matrix](http://docs.puppetlabs.com/guides/platforms.html#ruby-versions).
+To do the same tests in a CentOS container:
-By default the tests use a baseline version of Puppet.
+```
+$ bundle exec rake cent_6test_dock
+```
-If you have Ruby 2.x or want a specific version of Puppet,
-you must set an environment variable such as:
+To run VM or container-based tests for all OSs:
- export PUPPET_VERSION="~> 3.2.0"
+```
+$ bundle exec rake acceptance_vm
+$ bundle exec rake acceptance_dock
+```
-Install the dependencies like so...
+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.
- bundle install
+```
+$ BEAKER_destroy=no bundle exec rake cent_6test_vm
+```
-### Syntax and style
+You can then connect to the VM by navigating to the directory that contains
+its Vagrantfile and using standard Vagrant commands.
-The test suite will run [Puppet Lint](http://puppet-lint.com/) and
-[Puppet Syntax](https://github.com/gds-operations/puppet-syntax) to
-check various syntax and style things. You can run these locally with:
+```
+$ cd .vagrant/beaker_vagrant_files/centos-7.yml/
+$ vagrant status
+Current machine states:
- bundle exec rake lint
- bundle exec rake syntax
+centos-7 running (virtualbox)
+$ vagrant ssh
+$ sudo systemctl is-active opendaylight
+active
+$ logout
+$ vagrant destroy -f
+```
-### Running the unit tests
+### Tests in Continuous Integration
-The unit test suite covers most of the code. As mentioned above, please
-add tests if you're adding new functionality. Running the test suite is done
-with:
+The OpenDaylight Puppet module uses OpenDaylight's Jenkins silo to run tests
+in CI. Some tests are triggered when changes are proposed, others are triggered
+periodically to validate things haven't broken underneath us. See the
+[`puppet-*` tests][13] on the Jenkins web UI for a list of all tests.
- bundle exec rake spec
+[1]: https://wiki.opendaylight.org/view/Integration/Packaging "Integration/Packaging project wiki"
-Note also you can run the syntax, style and unit tests in one go with:
+[2]: https://trello.com/b/ACYMpTVD/opendaylight-integration "Integration Tello board"
- bundle exec rake test
+[3]: https://git.opendaylight.org/gerrit/#/q/project:integration/packaging/puppet-opendaylight "puppet-opendaylight Gerrit"
-#### Automatically run the tests
+[4]: https://lists.opendaylight.org/mailman/listinfo/integration-dev "integration-dev mailing list"
-During development of your puppet module you might want to run your unit
-tests a couple of times. You can use the following command to automate
-running the unit tests on every change made in the manifests folder.
+[5]: https://trello.com/b/ACYMpTVD/opendaylight-integration?menu=filter&filter=label:Int%2FPack "Integration/Packaging Trello cards"
- bundle exec guard
+[6]: http://webchat.freenode.net/?channels=opendaylight-integration "opendaylight-integration IRC web client"
-### Integration tests
+[7]: http://docs.opendaylight.org/en/latest/gerrit.html "OpenDaylight Gerrit docs"
-The unit tests just check the code runs, not that it does exactly what
-we want on a real machine. For that we're using
-[Beaker](https://github.com/puppetlabs/beaker).
+[8]: http://puppet-lint.com/ "Puppet lint"
-Beaker fires up a new virtual machine (using Vagrant) and runs a series of
-simple tests against it after applying the module. You can run our Beaker
-tests with:
+[9]: https://github.com/gds-operations/puppet-syntax "Puppet syntax"
- bundle exec rake acceptance
+[10]: https://github.com/puppet-community/metadata-json-lint "Metadata JSON lint"
-This will use the host described in `spec/acceptance/nodeset/default.yml`
-by default. To run against another host, set the `RS_SET` environment
-variable to the name of a host described by a `.yml` file in the
-`nodeset` directory. For example, to run against Fedora 20:
+[11]: https://github.com/puppetlabs/beaker "Beaker system tests"
- RS_SET=fedora-20-x64 bundle exec rake acceptance
+[12]: http://serverspec.org/resource_types.html "Serverspec"
-If you don't want to have to recreate the virtual machine every time you
-can use `BEAKER_DESTROY=no` and `BEAKER_PROVISION=no`. On the first run you will
-at least need `BEAKER_PROVISION` set to yes (the default). The Vagrantfile
-for the created virtual machines will be in `.vagrant/beaker_vagrant_files`.
+[13]: https://jenkins.opendaylight.org/releng/view/packaging/search/?q=puppet "Puppet CI jobs"
Code Review / integration / packaging / puppet-opendaylight.git / blobdiff