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
   4 we can do better.
   5
   6 #### Table of Contents
   7
   8 1. [Overview](#overview)
   9 2. [Communication](#communication)
  10    - [Trello](#trello)
  11    - [Email](#email)
  12    - [IRC](#irc)
  13 3. [Patches](#patches)
  14 4. [Testing](#testing)
  15    - [Test Dependencies](#test-dependencies)
  16    - [Coala Linting](#coala-linting)
  17    - [Syntax and Style Tests](#syntax-and-style-tests)
  18    - [Unit Tests](#unit-tests)
  19    - [System Tests](#system-tests)
  20    - [Tests in Continuous Integration](#tests-in-continuous-integration)
  21
  22 ## Overview
  23
  24 This is an offical upstream OpenDaylight codebase under the
  25 [Integration/Packaging project][1].
  26
  27 We use [Trello][2] to track TODOs and [Gerrit][3] to submit changes. Email
  28 the [integration-dev mailing list][4] to get in touch.
  29
  30 ## Communication
  31
  32 ### Trello
  33
  34 Enhancements, bugs and such are tracked on [Trello][2]. The Trello board is
  35 shared with other Integration projects and related efforts. Puppet-opendaylight
  36 is under the scope of the Integration/Packaging project, which has a column
  37 and [tag][5] to collect its cards. Cards related to puppet-opendaylight will
  38 typically mention it by name in the title.
  39
  40 ### Email
  41
  42 Please use the [integration-dev][4] mailing list to contact puppet-opendaylight
  43 developers. Please don't reach out to developers directly, per open source best
  44 practices.
  45
  46 ### IRC
  47
  48 To chat synchronously with developers, join the **#opendaylight-integration**
  49 on `chat.freenode.net`. If you're not familar with IRC, there are [web
  50 clients][6] that can make getting started easy.
  51
  52 ## Patches
  53
  54 Please use [Gerrit][3] to submit patches. See the [ODL Gerrit docs][7]
  55 general getting-started help.
  56
  57 Other tips for submitting excellent patches:
  58
  59 - Please provide test coverage for your changes.
  60 - If applicable, please provide documentation updates to reflect your changes.
  61
  62 ## Testing
  63
  64 ### Test Dependencies
  65
  66 A Vagrant environment is provided to help manage test dependencies. All
  67 software prerequisites and configuration for running all types of tests
  68 should be handled automatically.
  69
  70 To provision and connect to a Fedora-based VM with test tools installed:
  71
  72 ```
  73 $ vagrant up fedora
  74 $ vagrant ssh fedora
  75 # cd to ~/puppet-opendaylight and hack away
  76 ```
  77
  78 A CentOS-based VM is also provided.
  79
  80 ### Coala Linting
  81
  82 We use Coala (manged by tox) to run various linters, like spacing, line
  83 length, Markdown, YAML, JSON, etc.
  84
  85 ```
  86 $ tox
  87 ```
  88
  89 ### Syntax and Style Tests
  90
  91 We use [Puppet Lint][8], [Puppet Syntax][9] and [metadata-json-lint][10] to
  92 validate the module's syntax and style.
  93
  94 ```
  95 $ bundle exec rake lint
  96 $ bundle exec rake syntax
  97 $ bundle exec rake metadata_lint
  98 ```
  99
 100 ### Unit Tests
 101
 102 We use rspec-puppet to provide unit test coverage.
 103
 104 To run the unit tests and generate a coverage report, use:
 105
 106 ```
 107 $ bundle exec rake spec
 108 ```
 109
 110 To run the syntax, style and unit tests in one rake task (recommended), use:
 111
 112 ```
 113 $ bundle exec rake test
 114 ```
 115
 116 ### System Tests
 117
 118 While the [unit tests](#unit-tests) are able to quickly find many errors,
 119 they don't do much more than checking that the code compiles to a given state.
 120 To verify that the Puppet module behaves as desired once applied to a real,
 121 running system, we use [Beaker][11].
 122
 123 Beaker stands up virtual machines or containers using Vagrant or Docker,
 124 applies the OpenDaylight Puppet module with various combinations of params
 125 and uses [Serverspec][12] to validate the resulting system state.
 126
 127 To run Beaker tests against CentOS 7 in a VM using the latest OpenDaylight
 128 Carbon RPM, use:
 129
 130 ```
 131 $ bundle exec rake cent_8test_cbs_vm
 132 ```
 133
 134 To do the same tests in a CentOS container:
 135
 136 ```
 137 $ bundle exec rake cent_8test_cbs_dock
 138 ```
 139
 140 To run VM or container-based tests for all OSs:
 141
 142 ```
 143 $ bundle exec rake acceptance_vm
 144 $ bundle exec rake acceptance_dock
 145 ```
 146
 147 If you'd like to preserve the Beaker VM after a test run, perhaps for manual
 148 inspection or a quicker follow-up test run, use the `BEAKER_destroy`
 149 environment variable.
 150
 151 ```
 152 $ BEAKER_destroy=no bundle exec rake cent_8test_cbs_vm
 153 ```
 154
 155 You can then connect to the VM by navigating to the directory that contains
 156 its Vagrantfile and using standard Vagrant commands.
 157
 158 ```
 159 $ cd .vagrant/beaker_vagrant_files/centos-7.yml/
 160 $ vagrant status
 161 Current machine states:
 162
 163 centos-7                  running (virtualbox)
 164 $ vagrant ssh
 165 $ sudo systemctl is-active opendaylight
 166 active
 167 $ logout
 168 $ vagrant destroy -f
 169 ```
 170
 171 ### Tests in Continuous Integration
 172
 173 The OpenDaylight Puppet module uses OpenDaylight's Jenkins silo to run tests
 174 in CI. Some tests are triggered when changes are proposed, others are triggered
 175 periodically to validate things haven't broken underneath us. See the
 176 [`puppet-*` tests][13] on the Jenkins web UI for a list of all tests.
 177
 178 [1]: https://wiki.opendaylight.org/view/Integration/Packaging "Integration/Packaging project wiki"
 179
 180 [2]: https://trello.com/b/ACYMpTVD/opendaylight-integration "Integration Tello board"
 181
 182 [3]: https://git.opendaylight.org/gerrit/#/q/project:integration/packaging/puppet-opendaylight "puppet-opendaylight Gerrit"
 183
 184 [4]: https://lists.opendaylight.org/mailman/listinfo/integration-dev "integration-dev mailing list"
 185
 186 [5]: https://trello.com/b/ACYMpTVD/opendaylight-integration?menu=filter&filter=label:Int%2FPack "Integration/Packaging Trello cards"
 187
 188 [6]: http://webchat.freenode.net/?channels=opendaylight-integration "opendaylight-integration IRC web client"
 189
 190 [7]: http://docs.opendaylight.org/en/latest/gerrit.html "OpenDaylight Gerrit docs"
 191
 192 [8]: http://puppet-lint.com/ "Puppet lint"
 193
 194 [9]: https://github.com/gds-operations/puppet-syntax "Puppet syntax"
 195
 196 [10]: https://github.com/puppet-community/metadata-json-lint "Metadata JSON lint"
 197
 198 [11]: https://github.com/puppetlabs/beaker "Beaker system tests"
 199
 200 [12]: http://serverspec.org/resource_types.html "Serverspec"
 201
 202 [13]: https://jenkins.opendaylight.org/releng/view/packaging/search/?q=puppet "Puppet CI jobs"