we can do better.
#### Table of Contents
+
1. [Overview](#overview)
-1. [Communication](#communication)
- * [Issues](#issues)
- * [Gitter](#gitter)
-1. [Patches](#patches)
-1. [Testing](#testing)
- * [Test Dependencies](#test-dependencies)
- * [Syntax and Style Tests](#syntax-and-style-tests)
- * [Unit Tests](#unit-tests)
- * [System Tests](#system-tests)
- * [Tests in Continuous Integration](#tests-in-continuous-integration)
+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][1] 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][2]. 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. Previously
-answered questions end up becoming documentation for other people hitting
-similar issues. More eyes may get your question answered faster. Doing
-everything in the open keeps community members on an equal playing field
-(`@<respected company>` email addresses don't get priority, good questions do).
+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][1] 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][1] freely, even for small things! They are the
-primary method by which we track what's going on in the project.
+### IRC
-The labels 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`][3] 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`][4], [`piro:normal`][5]...)
-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][6]).
+- 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][7] 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][2] to submit patches.
-
-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][8] 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][9]!
-
-Other tips for submitting excellent pull requests:
-* 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).
-* If your PR contains a number of commits that provide one logical change,
-please squash them using `git rebase`.
-* Please provide test coverage for your changes.
-* If applicable, please provide documentation updates to reflect your changes.
+```
+$ vagrant up fedora
+$ vagrant ssh fedora
+# cd to ~/puppet-opendaylight and hack away
+```
-## Testing
+A CentOS-based VM is also provided.
-### Test Dependencies
+### Coala Linting
-The testing tools have a number of dependencies. We use [Bundler][10] to make
-installing them easy.
+We use Coala (manged by tox) to run various linters, like spacing, line
+length, Markdown, YAML, JSON, etc.
```
-[~/puppet-opendaylight]$ yum install -y rubygems ruby-devel gcc-c++ zlib-devel patch
-[~/puppet-opendaylight]$ gem install bundler
-[~/puppet-opendaylight]$ bundle install
+$ tox
```
### Syntax and Style Tests
-We use [Puppet Lint][11], [Puppet Syntax][12] and [metadata-json-lint][13] to
+We use [Puppet Lint][8], [Puppet Syntax][9] and [metadata-json-lint][10] to
validate the module's syntax and style.
```
-[~/puppet-opendaylight]$ bundle exec rake lint
-[~/puppet-opendaylight]$ bundle exec rake syntax
-[~/puppet-opendaylight]$ bundle exec rake metadata
+$ bundle exec rake lint
+$ bundle exec rake syntax
+$ bundle exec rake metadata_lint
```
### Unit Tests
To run the unit tests and generate a coverage report, use:
```
-[~/puppet-opendaylight]$ bundle exec rake spec
-# Snip test output
-Finished in 10.08 seconds (files took 0.50776 seconds to load)
-537 examples, 0 failures
-
-
-Total resources: 19
-Touched resources: 19
-Resource coverage: 100.00%
+$ bundle exec rake spec
```
-Note that we have a very large number of tests and 100% test coverage.
-
To run the syntax, style and unit tests in one rake task (recommended), use:
```
-[~/puppet-opendaylight]$ bundle exec rake test
+$ 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][14].
+running system, we use [Beaker][11].
-Beaker stands up virtual machines using Vagrant, applies the OpenDaylight
-Puppet module with various combinations of params and uses [Serverspec][15]
-to validate the resulting system state.
+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.
-Beaker depends on Vagrant ([Vagrant downloads page][18]) for managing VMs,
-which in turn depends on VirtualBox ([VirtualBox downloads page][19]) and
-the `kmod-VirtualBox` package.
+To run Beaker tests against CentOS 7 in a VM using the latest OpenDaylight
+Carbon RPM, use:
+
+```
+$ bundle exec rake cent_8test_cbs_vm
+```
-To run our Beaker tests against the primary target OS (CentOS 7) using the
-recommended RPM-based install method, use:
+To do the same tests in a CentOS container:
```
-[~/puppet-opendaylight]$ bundle exec rake centos
+$ bundle exec rake cent_8test_cbs_dock
```
-There are a number of pre-defined rake tasks to simplify running common
-Beaker tests.
+To run VM or container-based tests for all OSs:
```
-[~/puppet-opendaylight]$ bundle exec rake centos
-[~/puppet-opendaylight]$ bundle exec rake centos_tarball
-[~/puppet-opendaylight]$ bundle exec rake fedora_20
-[~/puppet-opendaylight]$ bundle exec rake fedora_21
-[~/puppet-opendaylight]$ bundle exec rake ubuntu
+$ bundle exec rake acceptance_vm
+$ bundle exec rake acceptance_dock
```
If you'd like to preserve the Beaker VM after a test run, perhaps for manual
environment variable.
```
-[~/puppet-opendaylight]$ BEAKER_destroy=no bundle exec rake centos
+$ BEAKER_destroy=no bundle exec rake cent_8test_cbs_vm
```
You can then connect to the VM by navigating to the directory that contains
its Vagrantfile and using standard Vagrant commands.
```
-[~/puppet-opendaylight]$ cd .vagrant/beaker_vagrant_files/centos-7.yml
-[~/puppet-opendaylight/.vagrant/beaker_vagrant_files/centos-7.yml]$ vagrant status
+$ cd .vagrant/beaker_vagrant_files/centos-7.yml/
+$ vagrant status
Current machine states:
centos-7 running (virtualbox)
-[~/puppet-opendaylight/.vagrant/beaker_vagrant_files/centos-7.yml]$ vagrant ssh
-[vagrant@centos-7 ~]$ sudo systemctl status opendaylight
-opendaylight.service - OpenDaylight SDN Controller
- Loaded: loaded (/usr/lib/systemd/system/opendaylight.service; enabled)
- Active: active (running) since Fri 2015-04-24 16:34:07 UTC; 1min 1s ago
- Docs: https://wiki.opendaylight.org/view/Main_Page
- http://www.opendaylight.org/
-[vagrant@centos-7 ~]$ logout
-[~/puppet-opendaylight/.vagrant/beaker_vagrant_files/centos-7.yml]$ vagrant destroy -f
+$ vagrant ssh
+$ sudo systemctl is-active opendaylight
+active
+$ logout
+$ vagrant destroy -f
```
-For more information about using Beaker, see [these docs][16].
-
### Tests in Continuous Integration
-We use [Travis CI][17] 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.
-
-
-[1]: https://github.com/dfarrell07/puppet-opendaylight/issues
-[2]: https://github.com/dfarrell07/puppet-opendaylight/pulls
-[3]: https://github.com/dfarrell07/puppet-opendaylight/labels/good-for-beginners
-[4]: https://github.com/dfarrell07/puppet-opendaylight/labels/prio%3Ahigh
-[5]: https://github.com/dfarrell07/puppet-opendaylight/labels/prio%3Anormal
-[6]: https://help.github.com/articles/closing-issues-via-commit-messages/
-[7]: https://gitter.im/dfarrell07/puppet-opendaylight
-[8]: http://chris.beams.io/posts/git-commit/
-[9]: http://cdn3.volusion.com/74gtv.tjme9/v/vspfiles/photos/Delicious%20Dozen-1.jpg
-[10]: http://bundler.io/
-[11]: http://puppet-lint.com/
-[12]: https://github.com/gds-operations/puppet-syntax
-[13]: https://github.com/puppet-community/metadata-json-lint
-[14]: https://github.com/puppetlabs/beaker
-[15]: http://serverspec.org/resource_types.html
-[16]: https://github.com/puppetlabs/beaker/wiki/How-to-Write-a-Beaker-Test-for-a-Module#typical-workflow
-[17]: https://travis-ci.org/dfarrell07/puppet-opendaylight
-[18]: https://www.vagrantup.com/downloads.html
-[19]: www.virtualbox.org/wiki/Linux_Downloads
+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.
+
+[1]: https://wiki.opendaylight.org/view/Integration/Packaging "Integration/Packaging project wiki"
+
+[2]: https://trello.com/b/ACYMpTVD/opendaylight-integration "Integration Tello board"
+
+[3]: https://git.opendaylight.org/gerrit/#/q/project:integration/packaging/puppet-opendaylight "puppet-opendaylight Gerrit"
+
+[4]: https://lists.opendaylight.org/mailman/listinfo/integration-dev "integration-dev mailing list"
+
+[5]: https://trello.com/b/ACYMpTVD/opendaylight-integration?menu=filter&filter=label:Int%2FPack "Integration/Packaging Trello cards"
+
+[6]: http://webchat.freenode.net/?channels=opendaylight-integration "opendaylight-integration IRC web client"
+
+[7]: http://docs.opendaylight.org/en/latest/gerrit.html "OpenDaylight Gerrit docs"
+
+[8]: http://puppet-lint.com/ "Puppet lint"
+
+[9]: https://github.com/gds-operations/puppet-syntax "Puppet syntax"
+
+[10]: https://github.com/puppet-community/metadata-json-lint "Metadata JSON lint"
+
+[11]: https://github.com/puppetlabs/beaker "Beaker system tests"
+
+[12]: http://serverspec.org/resource_types.html "Serverspec"
+
+[13]: https://jenkins.opendaylight.org/releng/view/packaging/search/?q=puppet "Puppet CI jobs"
Code Review / integration / packaging / puppet-opendaylight.git / blobdiff