Add CONTRIBUTING file; include in contribute.rst

GitHub recently added a feature that looks for a CONTRIBUTING file in
repo root and displays it whenever a user creates an issue or submits a
pull request. I took this opportunity to put some contribution
submission guidelines into that file, including it dynamically inside
our existing docs/contribute.rst file to eliminate unnecessary
redundancy.

CONTRIBUTING.rst

@@ -0,0 +1,37 @@
+Contribution submission guidelines
+==================================
+
+* Consider whether your new feature might be better suited as a
+  :doc:`plugin<plugins>`. Folks are usually available in the
+  `#pelican IRC channel`_ to help make that determination.
+* `Create a new git branch`_ specific to your change (as opposed to making
+  your commits in the master branch).
+* **Don't put multiple fixes/features in the same branch / pull request.**
+  For example, if you're hacking on a new feature and find a bugfix that
+  doesn't *require* your new feature, **make a new distinct branch and pull
+  request** for the bugfix.
+* Adhere to PEP8 coding standards whenever possible.
+* Check for unnecessary whitespace via ``git diff --check`` before committing.
+* **Add docs and tests for your changes**.
+* **Run all the tests on both Python 2.7+ and 3.2+** to ensure nothing was
+  accidentally broken.
+* First line of your commit message should start with present-tense verb, be 50
+  characters or less, and include the relevant issue number(s) if applicable.
+  *Example:* ``Ensure proper PLUGIN_PATH behavior. Refs #428.`` If the commit
+  *completely fixes* an existing bug report, please use ``Fixes #585`` or ``Fix
+  #585`` syntax (so the relevant issue is automatically closed upon PR merge).
+* After the first line of the commit message, add two returns and then a more
+  detailed explanation (when relevant).
+* **Use** ``hub pull-request`` when submitting code for a **pre-existing GitHub
+  Issue**. This isn't an absolute requirement, but makes the maintainers' lives
+  much easier! Specifically: `install hub
+  <https://github.com/defunkt/hub/#installation>`_ and then run `hub
+  pull-request <https://github.com/defunkt/hub/#git-pull-request>`_ to turn the
+  issue into a pull request containing your code.
+
+Check out our `Git Tips`_ page or ask on the `#pelican IRC channel`_ if you
+need assistance or have any questions about these guidelines.
+
+.. _`#pelican IRC channel`: http://webchat.freenode.net/?channels=pelican&uio=d4
+.. _`Create a new git branch`: https://github.com/getpelican/pelican/wiki/Git-Tips#making-your-changes
+.. _`Git Tips`: https://github.com/getpelican/pelican/wiki/Git-Tips

docs/contribute.rst

@@ -1,29 +1,34 @@
-How to contribute?
+How to contribute
-###################
+#################
-There are many ways to contribute to Pelican. You can enhance the
-documentation, add missing features, and fix bugs (or just report them).
 
-Don't hesitate to fork and make a pull request on GitHub. When doing so, please
+There are many ways to contribute to Pelican. You can improve the
-create a new feature branch as opposed to making your commits in the master
+documentation, add missing features, and fix bugs (or just report them). You
-branch.
+can also help out by reviewing and commenting on
+`existing issues <https://github.com/getpelican/pelican/issues>`_.
+
+Don't hesitate to fork Pelican and submit a pull request on GitHub. When doing
+so, please adhere to the following guidelines.
+
+.. include:: ../CONTRIBUTING.rst
 
 Setting up the development environment
 ======================================
 
-You're free to set up your development environment any way you like. Here is a
+While there are many ways to set up one's development environment, following
-way using the `virtualenv <http://www.virtualenv.org/>`_ and `virtualenvwrapper
+is a method that uses `virtualenv <http://www.virtualenv.org/>`_. If you don't
-<http://www.doughellmann.com/projects/virtualenvwrapper/>`_ tools. If you don't
+have ``virtualenv`` installed, you can install it via::
-have them, you can install these both of these packages via::
 
-    $ pip install virtualenvwrapper
+    $ pip install virtualenv
 
 Virtual environments allow you to work on Python projects which are isolated
 from one another so you can use different packages (and package versions) with
 different projects.
 
-To create a virtual environment, use the following syntax::
+To create and activate a virtual environment, use the following syntax::
 
-    $ mkvirtualenv pelican
+    $ virtualenv pelican ~/virtualenvs/pelican
+    $ cd ~/virtualenvs/pelican
+    $ . bin/activate
 
 To clone the Pelican source::
 
@@ -38,59 +43,76 @@ To install Pelican and its dependencies::
 
     $ python setup.py develop
 
+Coding standards
+================
+
+Try to respect what is described in the `PEP8 specification
+<http://www.python.org/dev/peps/pep-0008/>`_ when making contributions. This
+can be eased via the `pep8 <http://pypi.python.org/pypi/pep8>`_ or `flake8
+<http://pypi.python.org/pypi/flake8/>`_ tools, the latter of which in
+particular will give you some useful hints about ways in which the
+code/formatting can be improved.
+
+Building the docs
+=================
+
+If you make changes to the documentation, you should preview your changes
+before committing them::
+
+    $ pip install sphinx
+    $ cd src/pelican/docs
+    $ make html
+
+Open ``_build/html/index.html`` in your browser to preview the documentation.
+
 Running the test suite
 ======================
 
 Each time you add a feature, there are two things to do regarding tests:
-checking that the existing tests pass, and adding tests for the new feature
+check that the existing tests pass, and add tests for the new feature
 or bugfix.
 
-The tests live in "pelican/tests" and you can run them using the
+The tests live in ``pelican/tests`` and you can run them using the
-"discover" feature of unittest2::
+"discover" feature of ``unittest``::
 
-    $ unit2 discover
+    $ python -m unittest discover
 
-If you have made changes that affect the output of a Pelican-generated weblog,
+After making your changes and running the tests, you may see a test failure
-then you should update the output used by functional tests.
+mentioning that "some generated files differ from the expected functional tests
-To do so, you can use the following two commands::
+output." If you have made changes that affect the HTML output generated by
+Pelican, and the changes to that output are expected and deemed correct given
+the nature of your changes, then you should update the output used by the
+functional tests. To do so, you can use the following two commands::
 
     $ pelican -o pelican/tests/output/custom/ -s samples/pelican.conf.py \
         samples/content/
     $ pelican -o pelican/tests/output/basic/ samples/content/
 
-testing for python3
+Testing on Python 3.x
--------------------
+---------------------
 
-On Python 3, if you have installed the Py3k compatible versions of the
+Testing on Python 3.x currently requires some extra steps: installing
-plugins manual testing with ``unit2 discover`` is also straightforward.
+Python 3.x-compatible versions of dependent packages and plugins.
 
-However, you must tell tox to use those Py3k libraries. If you forget this,
+However, you must tell ``tox`` to use those Python 3.x-compatible libraries.
-tox will pull the regular packages from PyPi and the tests will fail.
+If you forget this, ``tox`` will pull the regular packages from PyPI, and the
+tests will fail.
 
-Tell tox about the local packages thusly: enter the source directory of
+Tell ``tox`` about the local packages thusly: enter the source directory of
-smartypants and run tox there. Do this again for typogrify and webassets.
+smartypants and run ``tox`` there. Do this again for the ``typogrify`` and
-Smartypants and typogrify do not have real tests, and webassets will fail
+``webassets`` packages. SmartyPants and Typogrify do not have real tests, and
-noisily, but as a result we get these libraries neatly packaged in tox's
+``webassets`` will fail noisily, but as a result we get these libraries neatly
-distshare directory. And this we need to run tox for Pelican.
+packaged in tox's ``distshare`` directory, which we need in order to run
+``tox`` for Pelican.
 
-Coding standards
+Python 3.x development tips
-================
+===========================
 
-Try to respect what is described in the `PEP8 specification
+Here are some tips that may be useful when doing some code for both Python 2.7
-<http://www.python.org/dev/peps/pep-0008/>`_ when providing patches. This can be
+and Python 3.x at the same time:
-eased via the `pep8 <http://pypi.python.org/pypi/pep8>`_ or `flake8
-<http://pypi.python.org/pypi/flake8/>`_ tools, the latter of which in
-particular will give you some useful hints about ways in which the
-code/formatting can be improved.
 
-Python3 support
+- Assume every string and literal is unicode (import unicode_literals):
-===============
 
-Here are some tips that may be useful when doing some code for both python2 and
-python3 at the same time:
-
-- Assume, every string and literal is unicode (import unicode_literals):
- 
   - Do not use prefix ``u'``.
   - Do not encode/decode strings in the middle of sth. Follow the code to the
     source (or target) of a string and encode/decode at the first/last possible