Enhance feedback and contributing guidelines

Many folks ask for help (via IRC or filing GitHub issues) without
sufficient detail and/or without first determining if the answers to
their questions might be better sourced elsewhere. These
documentation changes encourage users to follow certain guidelines
when reaching out for help.

CONTRIBUTING.rst

@@ -1,20 +1,91 @@
-Contribution submission guidelines
+Filing issues
-==================================
+-------------
+
+* Before you file an issue, try `asking for help`_ first.
+* If determined to file an issue, first check for `existing issues`_, including closed issues.
+
+.. _`asking for help`: `How to get help`_
+.. _`existing issues`: https://github.com/getpelican/pelican/issues
+
+How to get help
+---------------
+
+Before you ask for help, please make sure you do the following:
+
+1. Read the documentation_ thoroughly. If in a hurry, at least use the search
+   field that is provided at top-right on the documentation_ pages. Make sure
+   you read the docs for the Pelican version you are using.
+2. Use a search engine (e.g., DuckDuckGo, Google) to search for a solution to
+   your problem. Someone may have already found a solution, perhaps in the
+   form of a plugin_ or a specific combination of settings.
+
+3. Try reproducing the issue in a clean environment, ensuring you are using:
+
+* latest Pelican release (or an up-to-date git clone of Pelican master)
+* latest releases of libraries used by Pelican
+* no plugins or only those related to the issue
+
+If despite the above efforts you still cannot resolve your problem, be sure to
+include in your inquiry the following, preferably in the form of links to
+content uploaded to a `paste service`_, GitHub repository, or other
+publicly-accessible location:
+
+* Describe what version of Pelican you are running (output of ``pelican --version``
+  or the HEAD commit hash if you cloned the repo) and how exactly you installed
+  it (the full command you used, e.g. ``pip install pelican``).
+* If you are looking for a way to get some end result, prepare a detailed
+  description of what the end result should look like (preferably in the form of
+  an image or a mock-up page) and explain in detail what you have done so far to achieve it.
+* If you are trying to solve some issue, prepare a detailed description of how
+  to reproduce the problem. If the issue cannot be easily reproduced, it cannot
+  be debugged by developers or volunteers. Describe only the **minimum steps**
+  necessary to reproduce it (no extra plugins, etc.).
+* Upload your settings file or any other custom code that would enable people to
+  reproduce the problem or to see what you have already tried to achieve the
+  desired end result.
+* Upload detailed and **complete** output logs and backtraces (remember to add
+  the ``--debug`` flag: ``pelican --debug content [...]``)
+
+.. _documentation: http://docs.getpelican.com/
+.. _`paste service`: https://dpaste.de/
+
+Once the above preparation is ready, you can contact people willing to help via
+(preferably) the ``#pelican`` IRC channel or send a message to ``authors at getpelican dot com``.
+Remember to include all the information you prepared.
+
+The #pelican IRC channel
+........................
+
+* Because of differing time zones, you may not get an immediate response to your
+  question, but please be patient and stay logged into IRC — someone will almost
+  always respond if you wait long enough (it may take a few hours).
+* If you don't have an IRC client handy, use the webchat_ for quick feedback.
+* You can direct your IRC client to the channel using this `IRC link`_ or you
+  can manually join the ``#pelican`` IRC channel on the `freenode IRC network`_.
+
+.. _webchat: http://webchat.freenode.net/?channels=pelican&uio=d4
+.. _`IRC link`: irc://irc.freenode.org/pelican
+.. _`freenode IRC network`: http://www.freenode.org/
+
+
+Contributing code
+-----------------
+
+Before you submit a contribution, please ask whether it is desired so that you
+don't spend a lot of time working on something that would be rejected for a
+known reason. Consider also whether your new feature might be better suited as
+a plugin_ — you can `ask for help`_  to make that determination.
+
+Using Git and GitHub
+....................
 
-* Consider whether your new feature might be better suited as a plugin_. Folks
-  are usually available in the `#pelican IRC channel`_ if help is needed to
-  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.**
+* **Don't put multiple unrelated 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.3** 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
@@ -32,7 +103,22 @@ Contribution submission guidelines
   `hub pull-request <https://github.com/github/hub/#git-pull-request>`_ to
   turn your GitHub issue into a pull request containing your code.
 
-Check out our `Git Tips`_ page or ask on the `#pelican IRC channel`_ if you
+Contribution quality standards
+..............................
+
+* Adhere to `PEP8 coding standards`_ whenever possible. 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.
+* Make sure your code is compatible with Python 2.7, 3.3, and 3.4 — see our
+  `compatibility cheatsheet`_ for more details.
+* Add docs and tests for your changes. Undocumented and untested features will
+  not be accepted.
+* `Run all the tests`_ **on all versions of Python supported by Pelican** to
+  ensure nothing was accidentally broken.
+
+Check out our `Git Tips`_ page or `ask for help`_ if you
 need assistance or have any questions about these guidelines.
 
 .. _`plugin`: http://docs.getpelican.com/en/latest/plugins.html
@@ -42,4 +128,5 @@ need assistance or have any questions about these guidelines.
 .. _`Run all the tests`: http://docs.getpelican.com/en/latest/contribute.html#running-the-test-suite
 .. _`Git Tips`: https://github.com/getpelican/pelican/wiki/Git-Tips
 .. _`PEP8 coding standards`: http://www.python.org/dev/peps/pep-0008/
-
+.. _`ask for help`: `How to get help`_
+.. _`compatibility cheatsheet`: http://docs.getpelican.com/en/latest/contribute.html#python-3-development-tips

README.rst

@@ -45,16 +45,10 @@ You can access the source code at: https://github.com/getpelican/pelican
 
 If you feel hackish, have a look at the explanation of `Pelican's internals`_.
 
-Feedback / Contact us
+How to get help, contribute, or provide feedback
----------------------
+------------------------------------------------
 
-If you want to see new features in Pelican, don't hesitate to offer
+See our `contribution submission and feedback guidelines <CONTRIBUTING.rst>`_.
-suggestions, clone the repository, etc. There are many ways to contribute_.
-That's open source, dude!
-
-Send a message to "authors at getpelican dot com" with any requests/feedback! You
-can also join the team at `#pelican on Freenode`_ (or if you don't have an IRC
-client handy, use the webchat_ for quick feedback.
 
 .. Links
 
@@ -62,8 +56,5 @@ client handy, use the webchat_ for quick feedback.
 .. _reStructuredText: http://docutils.sourceforge.net/rst.html
 .. _Markdown: http://daringfireball.net/projects/markdown/
 .. _Jinja2: http://jinja.pocoo.org/
-.. _`Pelican documentation`: http://docs.getpelican.com/latest/
+.. _`Pelican documentation`: http://docs.getpelican.com/
 .. _`Pelican's internals`: http://docs.getpelican.com/en/latest/internals.html
-.. _`#pelican on Freenode`: irc://irc.freenode.net/pelican
-.. _webchat: http://webchat.freenode.net/?channels=pelican&uio=d4
-.. _contribute: http://docs.getpelican.com/en/latest/contribute.html

docs/contribute.rst

@@ -1,13 +1,13 @@
-How to contribute
+Contributing and Feedback Guidelines
-#################
+####################################
 
 There are many ways to contribute to Pelican. You can improve the
 documentation, add missing features, and fix bugs (or just report them). You
 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
+Don't hesitate to fork Pelican and submit an issue or pull request on GitHub.
-so, please adhere to the following guidelines.
+When doing so, please adhere to the following guidelines.
 
 .. include:: ../CONTRIBUTING.rst
 
@@ -47,16 +47,6 @@ Or using ``pip``::
 
     $ pip install -e .
 
-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
 =================
 

docs/faq.rst

@@ -6,16 +6,7 @@ Here are some frequently asked questions about Pelican.
 What's the best way to communicate a problem, question, or suggestion?
 ======================================================================
 
-If you have a problem, question, or suggestion, please start by striking up a
+Please read our :doc:`feedback guidelines <contribute>`.
-conversation on `#pelican on Freenode <irc://irc.freenode.net/pelican>`_.
-Those who don't have an IRC client handy can jump in immediately via
-`IRC webchat <http://webchat.freenode.net/?channels=pelican&uio=d4>`_. Because
-of differing time zones, you may not get an immediate response to your
-question, but please be patient and stay logged into IRC — someone will almost
-always respond if you wait long enough (it may take a few hours).
-
-If you're unable to resolve your issue or if you have a feature request, please
-refer to the `issue tracker <https://github.com/getpelican/pelican/issues>`_.
 
 How can I help?
 ================

docs/index.rst

@@ -47,20 +47,10 @@ Source code
 
 You can access the source code at: https://github.com/getpelican/pelican
 
-Feedback / Contact us
+How to get help, contribute, or provide feedback
----------------------
+------------------------------------------------
 
-If you want to see new features in Pelican, don't hesitate to offer suggestions,
+See our :doc:`feedback and contribution submission guidelines <contribute>`.
-clone the repository, etc. There are many ways to :doc:`contribute<contribute>`.
-That's open source, dude!
-
-Send a message to "authors at getpelican dot com" with any requests/feedback.
-For a more immediate response, you can also join the team via IRC at
-`#pelican on Freenode`_ — if you don't have an IRC client handy, use the
-webchat_ for quick feedback. If you ask a question via IRC and don't get an
-immediate response, don't leave the channel! It may take a few hours because
-of time zone differences, but if you are patient and remain in the channel,
-someone will almost always respond to your inquiry.
 
 Documentation
 -------------
@@ -93,5 +83,3 @@ Documentation
 .. _`Pelican documentation`: http://docs.getpelican.com/latest/
 .. _`Pelican's internals`: http://docs.getpelican.com/en/latest/internals.html
 .. _`Pelican plugins`: https://github.com/getpelican/pelican-plugins
-.. _`#pelican on Freenode`: irc://irc.freenode.net/pelican
-.. _webchat: http://webchat.freenode.net/?channels=pelican&uio=d4