initial pass on contributing doc

Author: alimanfoo

docs/contributing.rst

@@ -62,11 +62,11 @@ a core set of functionalities, and available time for development, review and ma
 of new features is limited. But if you have a great idea, please don't let that stop
 you posting it on GitHub, just please don't be offended if we respond cautiously.
 
-Working with the code
----------------------
+Contributing code and/or documentation
+--------------------------------------
 
-Forking
-~~~~~~~
+Forking the repository
+~~~~~~~~~~~~~~~~~~~~~~
 
 The Zarr source code is hosted on GitHub at the following location:
 
@@ -93,9 +93,108 @@ the repository, you can do something like the following::
     $ virtualenv --no-site-packages --python=/usr/bin/python3.6 ~/pyenv/zarr-dev
     $ source ~/pyenv/zarr-dev/bin/activate
     $ pip install -r requirements_dev.txt
+    $ pip install -r requirements_dev_optional.txt
+    $ pip install -e .
+
+To verify that your development environment is working, you can run the unit tests::
+
+    $ pytest -v zarr
+
+Creating a branch
+~~~~~~~~~~~~~~~~~
+
+It's best to create a new, separate branch for each piece of work you want to do. E.g.::
+
+    git checkout -b shiny-new-feature
+
+This changes your working directory to the shiny-new-feature branch. Keep any changes in
+this branch specific to one bug or feature so it is clear what the branch brings to
+Zarr.
 
-To verify that your development environment is working, you can run the unit test suite::
+To update this branch with latest code from Zarr, you can retrieve the changes from
+the master branch::
+
+    git fetch upstream
+    git rebase upstream/master
+
+This will replay your commits on top of the latest Zarr git master. If this leads to
+merge conflicts, these need to be resolved before submitting a pull request.
+
+Before you do any new work or submit a pull request, please open an issue on GitHub to
+report the bug or propose the feature you'd like to add.
+
+Running the test suite
+~~~~~~~~~~~~~~~~~~~~~~
+
+Zarr includes a suite of unit tests, as well as doctests included in function and class
+docstrings and in the tutorial and storage spec. The simplest way to run the unit tests
+is to invoke::
 
     $ pytest -v zarr
 
+To also run the doctests within docstrings, run::
+
+    $ pytest -v --doctest-modules zarr
+
+To run the doctests within the tutorial and storage spec, run::
+
+    $ python -m doctest -o NORMALIZE_WHITESPACE -o ELLIPSIS docs/tutorial.rst docs/spec/v2.rst
+
+Tests can be run under different Python versions using tox. E.g. (assuming you have the
+corresponding Python interpreters installed on your system)::
+
+    $ tox -e py27,py34,py35,py36
+
+Zarr currently supports Python 2.7 and Python 3.4-3.6, so the above command must
+succeed before code can be accepted into the main code base. Note that only the py36
+tox environment runs the doctests, i.e., doctests only need to succeed under Python 3.6.
+
+All tests are automatically run via Travis (Linux) and AppVeyor (Windows) continuous
+integration services for every pull request. Tests must pass under both services before
+code can be accepted.
+
+Code standards
+~~~~~~~~~~~~~~
+
+All code must conform to the PEP8 standard. Regarding line length, lines up to 100
+characters are allowed, although please try to keep under 90 wherever possible.
+Conformance can be checked by running::
+
+    $ flake8 --max-line-length=100 zarr
+
+This is automatically run when invoking ``tox -e py36``.
+
+Test coverage
+~~~~~~~~~~~~~
+
+Zarr maintains 100% test coverage under the latest Python stable release (currently
+Python 3.6). Both unit tests and docstring doctests are included when computing
+coverage. Running ``tox -e py36`` will automatically run the test suite with coverage
+and produce a coverage report. This should be 100% before code can be accepted into the
+main code base.
+
+When submitting a pull request, coverage will also be collected across all supported
+versions via the Coveralls service, and will be reported back within the pull request.
+Coveralls coverage must also be 100% before code can be accepted.
+
+Documentation
+~~~~~~~~~~~~~
+
+Docstrings for user-facing classes and functions should follow the `numpydoc
+<https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt>`_ standard,
+including sections for Parameters and Examples. All examples will be run as doctests
+under Python 3.6.
+
+Zarr uses Sphinx for documentation, hosted on readthedocs.org. Documentation is
+written in the RestructuredText markup language (.rst files) in the ``docs`` folder.
+The documentation consists both of prose and API documentation. All user-facing classes
+and functions should be included in the API documentation, under the ``docs/api``
+folder. Any new features or important usage information should be included in the
+tutorial (``docs/tutorial.rst``). Any changes should also be included in the release
+notes (``docs/release.rst``).
+
+The documentation can be built by running::
+
+    $ tox -e docs
 
+The resulting built documentation will be available in the ``.tox/docs/tmp/html`` folder.