X-Git-Url: https://git.opendaylight.org/gerrit/gitweb?a=blobdiff_plain;f=CONTRIBUTING.markdown;h=6c9bd11394d0c5a6703495354660c082cdfb9add;hb=refs%2Fchanges%2F83%2F68783%2F3;hp=f1526929f1e4b30bcc0182a6b2917d5d8321b1c0;hpb=556142104d6dfbccb4a0703f0415681439f64338;p=integration%2Fpackaging%2Fpuppet-opendaylight.git diff --git a/CONTRIBUTING.markdown b/CONTRIBUTING.markdown index f152692..6c9bd11 100644 --- a/CONTRIBUTING.markdown +++ b/CONTRIBUTING.markdown @@ -4,116 +4,97 @@ 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) - * [IRC channel](#irc-channel) -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 -(`@` 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. -### IRC channel +## Testing -Feel free to join us at **#opendaylight-integration** on `chat.freenode.net`. You can also use web client for Freenode to join us at [webchat][19]. +### Test Dependencies -## Patches +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. -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][7] 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][8]! - -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. +To provision and connect to a Fedora-based VM with test tools installed: -## Testing +``` +$ vagrant up fedora +$ vagrant ssh fedora +# cd to ~/puppet-opendaylight and hack away +``` -### Test Dependencies +A CentOS-based VM is also provided. + +### Coala Linting -The testing tools have a number of dependencies. We use [Bundler][9] 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]$ sudo yum install -y rubygems ruby-devel gcc-c++ zlib-devel \ - patch redhat-rpm-config make -[~/puppet-opendaylight]$ gem install bundler -[~/puppet-opendaylight]$ bundle install -[~/puppet-opendaylight]$ bundle update +$ tox ``` ### Syntax and Style Tests -We use [Puppet Lint][10], [Puppet Syntax][11] and [metadata-json-lint][12] 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 @@ -123,23 +104,13 @@ We use rspec-puppet to provide unit test coverage. 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 @@ -147,33 +118,30 @@ To run the syntax, style and unit tests in one rake task (recommended), use: 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][13]. +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. -Beaker stands up virtual machines using Vagrant, applies the OpenDaylight -Puppet module with various combinations of params and uses [Serverspec][14] -to validate the resulting system state. +To run Beaker tests against CentOS 7 in a VM using the latest OpenDaylight +Carbon RPM, use: -Beaker depends on Vagrant ([Vagrant downloads page][17]) for managing VMs, -which in turn depends on VirtualBox ([VirtualBox downloads page][18]) and -the `kmod-VirtualBox` package. +``` +$ 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_7_docker -[~/puppet-opendaylight]$ bundle exec rake centos -[~/puppet-opendaylight]$ bundle exec rake centos_tarball -[~/puppet-opendaylight]$ bundle exec rake fedora_22 -[~/puppet-opendaylight]$ bundle exec rake ubuntu_1404 -[~/puppet-opendaylight]$ bundle exec rake ubuntu_1404_docker +$ 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 @@ -181,54 +149,54 @@ inspection or a quicker follow-up test run, use the `BEAKER_destroy` 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][15]. - ### Tests in Continuous Integration -We use [Travis CI][16] 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]: http://chris.beams.io/posts/git-commit/ -[8]: http://cdn3.volusion.com/74gtv.tjme9/v/vspfiles/photos/Delicious%20Dozen-1.jpg -[9]: http://bundler.io/ -[10]: http://puppet-lint.com/ -[11]: https://github.com/gds-operations/puppet-syntax -[12]: https://github.com/puppet-community/metadata-json-lint -[13]: https://github.com/puppetlabs/beaker -[14]: http://serverspec.org/resource_types.html -[15]: https://github.com/puppetlabs/beaker/wiki/How-to-Write-a-Beaker-Test-for-a-Module#typical-workflow -[16]: https://travis-ci.org/dfarrell07/puppet-opendaylight -[17]: https://www.vagrantup.com/downloads.html -[18]: www.virtualbox.org/wiki/Linux_Downloads -[19]: http://webchat.freenode.net/?channels=opendaylight-integration +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"