Fixed #2 -- added "contributing" documentation.

Author: mboersma

docs/contributing/standards.rst

@@ -1,6 +1,6 @@
 :title: Coding Standards
-:description: -- todo: change me
-:keywords: deis, documentation, contributing, developer, setup
+:description: Coding Standards for the Deis Project
+:keywords: deis, contributing, coding, python, test, tests, testing
 
 .. _standards:
 
@@ -9,36 +9,56 @@ Coding Standards
 
 Deis is a `python`_ project. We chose python over other compelling
 languages because it is widespread, well-documented, and friendly to
-a large number of developers. We think open source code benefits from
-many eyes upon it.
+a large number of developers. Source code benefits from many eyes
+upon it.
+
+`The Zen of Python`_ emphasizes simple over clever, and we agree.
+Readability counts. Deis also aims for complete test coverage.
 
 Contributors to deis should feel welcome to make changes to any part
 of the codebase. To create a proper github pull request for inclusion
 into the official repository, your code must pass two tests:
 
-- :ref:`flake8`
-- :ref:`coverage`
+- :ref:`make_flake8`
+- :ref:`make_coverage`
 
 
-.. _flake8:
+.. _make_flake8:
 
 ``make flake8``
 ---------------
 
-::
+`flake8`_ is a helpful command-line tool that combines the output of
+`pep8 <pep8_tool_>`_, `pyflakes`_, and `mccabe`_.
+
+.. code-block:: console
 
 	$ cd $HOME/projects/deis
 	$ make flake8
 	flake8
 	$
 
+No output, as above, means ``flake8`` found no errors. If errors
+are reported, fix them in your source code and try ``flake8`` again.
+
+The Deis project adheres to `PEP8`_, the python code style guide,
+with the exception that we allow lines up to 99 characters in length.
+Docstrings and tests are also required for all public methods, although
+``flake8`` does not enforce this.
+
+Default settings for ``flake8`` are in the ``[flake8]`` section of the
+setup.cfg file in the project root.
+
 
-.. _coverage:
+.. _make_coverage:
 
 ``make coverage``
 -----------------
 
-::
+Once your code passes the style checker, run the test suite and
+ensure that everything passes and that code coverage has not declined.
+
+.. code-block:: console
 
 	$ cd $HOME/projects/deis
 	$ make coverage
@@ -53,5 +73,27 @@ into the official repository, your code must pass two tests:
 	coverage html
 	$
 
+If a test fails, fixing it is obviously the first priority. And if you
+have introduced new code, it must be accompanied by unit tests.
+
+In the example above, all tests passed and ``coverage`` created a report
+of what code was exercised while the tests were running. Open the file
+``htmlcov/index.html`` under the project's root and ensure that the
+overall coverage percentage has not receded as a result of your
+changes. Current test coverage can be found here:
+
+.. image:: https://coveralls.io/repos/opdemand/deis/badge.png?branch=master
+    :target: https://coveralls.io/r/opdemand/deis?branch=master
+    :alt: Coverage Status
+
+Now create a GitHub pull request with a description of what your code
+fixes or improves. That's it!
+
 
 .. _python: http://www.python.org/
+.. _flake8: https://pypi.python.org/pypi/flake8/
+.. _pep8_tool: https://pypi.python.org/pypi/pep8/
+.. _pyflakes: https://pypi.python.org/pypi/pyflakes/
+.. _mccabe: https://pypi.python.org/pypi/mccabe/
+.. _PEP8: http://www.python.org/dev/peps/pep-0008/
+.. _`The Zen of Python`: http://www.python.org/dev/peps/pep-0020/