48e0ef86bf
The upstream docs structure is changing, so this change updates our existing docs into contributor and install guide sections. Change-Id: I70bd519f3be74513a5f99f7b94719d7c07424a5b Depends-On: Ia750cb049c0f53a234ea70ce1f2bbbb7a2aa9454
96 lines
3.1 KiB
ReStructuredText
96 lines
3.1 KiB
ReStructuredText
.. _coding_style:
|
||
|
||
============
|
||
Coding Style
|
||
============
|
||
|
||
.. note:: this document is a work in progress and the content will evolve. Any contribution is welcome though ;-)
|
||
|
||
- Read this page
|
||
- Make sure that what you're going to code is not already a work in
|
||
progress
|
||
- Make sure you're familiar with Puppet Syntax, Lint_, Rspec_ and Beaker_
|
||
- If you want to create a new module, read `New Module <http://docs.openstack.org/developer/puppet-openstack-guide/new-module.html>`_.
|
||
|
||
.. _Lint: http://puppet-lint.com/
|
||
.. _Rspec: http://rspec-puppet.com/
|
||
.. _Beaker: https://github.com/puppetlabs/beaker
|
||
|
||
|
||
Best practices
|
||
==============
|
||
|
||
Deprecation
|
||
~~~~~~~~~~~
|
||
|
||
Any patch **must be** backward compatible.
|
||
|
||
It meansː
|
||
|
||
- do not break the interface (deprecate parameters for at least one
|
||
cycle, and add a warning for our users)
|
||
- do not change default parameters (except if you have a good reason
|
||
but your commit message must explain it)
|
||
|
||
Commit message
|
||
~~~~~~~~~~~~~~
|
||
|
||
Please read GitCommitMessages_
|
||
|
||
.. _GitCommitMessages: https://wiki.openstack.org/wiki/GitCommitMessages
|
||
|
||
Consistency
|
||
~~~~~~~~~~~
|
||
|
||
We have a lot of modules to maintain, please keep our code consistent.
|
||
Before adding new parameters or new classes, see if other modules
|
||
already implement them and keep consistent. See also our common libraries
|
||
`OpenStackLib <http://git.openstack.org/cgit/openstack/puppet-openstacklib/>`__
|
||
|
||
Config file defaults and parameters
|
||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||
|
||
We want users that don't override a value to get the default for the
|
||
service being configured. Many of the parameters passed in to classes
|
||
and defined types translate directly into a config file setting. When a
|
||
parameter translates directly to a config file value, and the value is
|
||
optional, it should be set to ``$::os_service_default``. This is a
|
||
special value that will ensure that the service default is used by
|
||
removing any existing value from the config file.
|
||
|
||
Empty parameters
|
||
~~~~~~~~~~~~~~~~
|
||
|
||
When you need to specify an empty (nil) parameter, using
|
||
`undef <https://docs.puppetlabs.com/puppet/latest/reference/lang_data_undef.html>`__
|
||
is the best choice. Do not useː " (not Puppetish) or false (undef is
|
||
false if tested as a boolean).
|
||
|
||
Testing
|
||
=======
|
||
|
||
Everything about testing you can find here_.
|
||
|
||
.. _here: http://docs.openstack.org/developer/puppet-openstack-guide/testing.html
|
||
|
||
Documentation
|
||
=============
|
||
|
||
- Validate all parameters are documented. They are required and lint
|
||
will check it.
|
||
- If possible, keep examples/\*.pp updated, they are very useful for
|
||
our users.
|
||
- Comment your code when needed (temporary workarounds, TODO, etc).
|
||
|
||
Asking for review
|
||
=================
|
||
|
||
Different ways to get reviewsː
|
||
|
||
- Go on IRC ``#puppet-openstack`` (freenode) and gently ask for
|
||
reviews. If you need to discuss about already reviewed code, you can
|
||
ping the reviewers.
|
||
- Add your patch on the Puppet OpenStack `meeting <http://docs.openstack.org/developer/puppet-openstack-guide/meetings.html>`_ Agenda (in Open Discussion section).
|
||
- Use the `Mailing list <http://docs.openstack.org/developer/puppet-openstack-guide/mailing-list.html>`_.
|
||
|