2012-05-01 05:01:44 +00:00
# Contributing to Anvil
2012-03-10 00:21:36 +00:00
## General
2012-05-01 05:01:44 +00:00
Anvil is written in python (we should be compatible with ``python >= 2.6``).
2012-03-10 00:21:36 +00:00
2012-05-06 17:52:07 +00:00
Anvil's official repository is located on GitHub at: https://github.com/yahoo/Openstack-Anvil.git.
2012-03-10 00:21:36 +00:00
2012-05-06 17:54:23 +00:00
Besides the master branch that tracks the OpenStack ``trunk`` tags will maintained for all OpenStack releases starting with `essex` .
2012-03-10 00:21:36 +00:00
2012-05-06 17:52:07 +00:00
The primary script in anvil is ``smithy``, which performs the bulk of the work for anvil's use cases (it acts as the main program entry-point).
2012-03-10 00:21:36 +00:00
2012-05-06 17:52:07 +00:00
A number of additional scripts/goodies can be found in the ``tools`` directory that may or may not be useful to you.
2012-03-10 00:21:36 +00:00
## Documentation
2012-04-21 01:12:53 +00:00
Please create documentation in the ``docs/`` folder which will be synced with:
2012-03-10 00:21:36 +00:00
2012-05-01 05:01:44 +00:00
http://readthedocs.org/docs/anvil/
2012-03-10 00:21:36 +00:00
This will suffice until a more *official* documentation site can be made.
## Style
* Please attempt to follow [pep8] for all code submitted.
* Please also attempt to run [pylint] all code submitted.
2012-05-06 17:54:23 +00:00
* Please also attempt to run the [yaml] validation if you adjust any [yaml] files in the `conf` directory.
2012-05-06 17:50:19 +00:00
2012-05-06 17:51:00 +00:00
Use: ``./checks.sh`` to aid in running the 3 checks listed.
2012-03-10 00:31:21 +00:00
2012-03-10 00:21:36 +00:00
## Environment Variables
2012-05-06 17:50:19 +00:00
* The ``OS_*`` environment variables should be the only ones used for all authentication to OpenStack clients as documented in the [CLI Auth] wiki page.
2012-03-10 00:21:36 +00:00
2012-03-13 06:52:14 +00:00
## Documentation
2012-03-13 06:50:00 +00:00
2012-04-21 01:12:53 +00:00
Documentation should all be written in [markdown] or [rst]. Although github does support other formats it seems better just to stabilize on one of those.
2012-03-10 00:21:36 +00:00
2012-03-14 23:01:22 +00:00
## Style Commandments
1. Read http://www.python.org/dev/peps/pep-0008/
1. Read http://www.python.org/dev/peps/pep-0008/ again
1. Read on
### Overall
1. Put two newlines between top-level code (funcs, classes, etc)
1. Put one newline between methods in classes and anywhere else
1. Do not write "except:", use "except Exception:" at the very least
1. Include your name with TODOs as in "#TODO(termie)"
1. Do not name anything the same name as a built-in or reserved word
### Imports
1. Do not import objects, only modules
1. Do not import more than one module per line
1. Do not make relative imports
1. Order your imports by the full module path
1. Organize your imports in lexical order (TBD)
2012-03-10 00:21:36 +00:00
[CLI Auth]: http://wiki.openstack.org/CLIAuth
2012-05-06 17:54:23 +00:00
[yaml]: http://en.wikipedia.org/wiki/YAML
2012-03-10 00:21:36 +00:00
[pep8]: http://www.python.org/dev/peps/pep-0008/
[pylint]: http://pypi.python.org/pypi/pylint
2012-03-13 06:50:19 +00:00
[markdown]: http://daringfireball.net/projects/markdown/
2012-04-06 05:22:50 +00:00
[rst]: http://docutils.sourceforge.net/docs/user/rst/quickstart.html
2012-03-14 23:01:22 +00:00