Docs updates recovered from a broken git repo.

Draft release process doc to try force myself into more
structured releases in the future.

A few initial notes on how to report errors.

Added a few common exceptions to the FAQ.

Removed supported versions from feature matrix. They are all
available in setup.py metadata.

Move JWT tokens to grant types where it (confusingly) belongs.

8 files changed, 183 insertions, 20 deletions

diff --git a/docs/error_reporting.rst b/docs/error_reporting.rst
new file mode 100644
index 0000000..705f447
--- /dev/null
+++ b/docs/error_reporting.rst
@@ -0,0 +1,61 @@
+Reporting bugs how-to
+=====================
+
+Bugs are reported by opening a new Github issue and you should never hesitate
+to do so. Indeed, please open an issue if the documentation is unclear, you
+think the API is unintuitive or if you just want some help using the library.
+
+OAuthLib strive to have helpful exception messages and if you run into a
+case where that is not true please let us know!
+
+When reporting bugs, especially when they are hard or impossible to reproduce,
+it is useful to include logging output. You can enable logging for all
+oauthlib modules by adding a logger to the `oauthlib` namespace. 
+
+.. code-block:: python
+
+    import logging
+    import sys
+    log = logging.getLogger('oauthlib')
+    log.addHandler(logging.StreamHandler(sys.stdout))
+    log.setLevel(logging.DEBUG)
+
+If you are using a library that builds upon OAuthLib please also enable the
+logging for their modules, e.g. for `requests-oauthlib`
+
+.. code-block:: python
+
+    log = logging.getLogger('requests-oauthlib')
+    log.addHandler(logging.StreamHandler(sys.stdout))
+    log.setLevel(logging.DEBUG)
+
+Unfortunately we can't always respond quickly to issues and to help us help you
+please try and include steps to reproduce the issue. A short example can go
+far, e.g. instead of
+
+.. code-block:: python
+
+        # oauthlib crashes when trying to sign foobar urls.
+
+aim for
+
+.. code-block:: python
+
+        # OAuth 1 Clients raise a value error for the example below
+        from oauthlib.oauth1 import Client
+        client = Client('client-id')
+        headers = {'Content-Type': 'application/x-www-form-urlencoded'}
+        body = 'hello world'
+        client.sign('https://foo.bar', headers=headers, body=body)
+
+An example like this immediately tells us two things
+
+1. You might want to have the body sign but it was unclear that it needs to be
+   properly encoded first.
+
+2. You might not want the body signed but follow an example where the header was
+   provided and you were not sure if you could simply skip supplying the header.
+
+The root cause could certainly be much more complicated but in either case
+steps to reproduce allow us to speculate as to what might cause the problem and
+lower the number of round trips needed to find a solution.
diff --git a/docs/faq.rst b/docs/faq.rst
index 74b6312..d48e7ef 100644
--- a/docs/faq.rst
+++ b/docs/faq.rst
@@ -1,34 +1,91 @@
-F.A.Q
-=====
+Frequently asked questions
+==========================
+
+How do I enable logging for OAuthLib?
+-------------------------------------
+
+    See :doc:`error_reporting`.
 
 What parts of OAuth 1 & 2 are supported?
+----------------------------------------
+
     See :doc:`feature_matrix`.
 
+OAuth 1 with RSA-SHA1 signatures says "could not import Crypto". What should I do?
+----------------------------------------------------------------------------------
+
+    Install either PyCrypto or Cryptography via pip.
+
+.. code-block:: sh
+
+    $ pip install pycrypto
+    $ pip install cryptography
+
+OAuth 2 ServiceApplicationClient says "could not import jwt". What should I do?
+-------------------------------------------------------------------------------
+
+    Install pyjwt and pycrypto with pip.
+
+.. code-block:: sh
+
+    $ pip install pyjwt pycrypto
+
+What does ValueError `Only unicode objects are escapable. Got one of type X.` mean?
+-----------------------------------------------------------------------------------
+
+   OAuthLib uses unicode everywhere and when creating a OAuth 1 signature
+   a number of parameters need to be percent encoded (aka escaped). At least
+   one parameter could not be encoded. Usually because `None` or a non UTF-8 
+   encoded string was supplied.
+
+What does ValueError `Error trying to decode a non urlencoded string` mean?
+---------------------------------------------------------------------------
+
+    You are trying to decode a response which is not properly encoded, e.g.
+    include non percent encoded characters such as `£`. Which could be because
+    it has already been decoded by your web framework. 
+    
+    If you believe it contains characters that should be excempt from this
+    check please open an issue and state why.
+    
+     
 What is the difference between a client and a consumer?
+-------------------------------------------------------
+
     None, they both refer to the third-party accessing protected resources
     from an OAuth provider on behalf of a user. In order to do so they have
     to obtain authorization from said user, which is what the `Auth` in `OAuth`
     stands for.
 
 How do I use OAuthLib with Google, Twitter and other providers?
+---------------------------------------------------------------
+
     Most people will be using OAuthLib indirectly. Clients will want to look at
     `requests-oauthlib`_.
     
 How do I use OAuthlib as a provider with Django, Flask and other web frameworks?
+--------------------------------------------------------------------------------
+
     Providers using Django should seek out `django-oauth-toolkit`_
     and those using Flask `flask-oauthlib`_. For other frameworks,
     please get in touch by opening a `GitHub issue`_, on `G+`_ or
     on IRC #oauthlib irc.freenode.net.
 
 What is the difference between authentication and authorization?
+----------------------------------------------------------------
+
     See `difference`_.
 
 Very briefly, what is the biggest difference between OAuth 1 and 2?
+-------------------------------------------------------------------
+
     OAuth 2 is much simpler since it requires the use of TLS whereas OAuth 1
     had the requirement to work securely without TLS. To be secure without TLS
     OAuth 1 required each request to be signed which can be cumbersome.
 
 Some argue OAuth 2 is worse than 1, is that true?
+-------------------------------------------------
+
     Correctly implemented, OAuth 2 is better in many ways than OAuth 1. Getting
     it right is not trivial and a task OAuthLib aims to help make simple.
 
diff --git a/docs/feature_matrix.rst b/docs/feature_matrix.rst
index 5dbd6ce..cd9b509 100644
--- a/docs/feature_matrix.rst
+++ b/docs/feature_matrix.rst
@@ -1,17 +1,5 @@
-Supported features, platforms and python versions
-=================================================
-
-Supported versions
-------------------
-
-* 2.6
-* 2.7
-* 3.2
-* 3.3
-* pypy
-
-Supported features
-------------------
+Supported features and platforms
+================================
 
 OAuth 1 is fully supported per the RFC for both clients and providers.
 Extensions and variations that are outside the spec are not supported.
diff --git a/docs/index.rst b/docs/index.rst
index efd97b2..f1d380d 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -7,9 +7,11 @@ Welcome to OAuthLib's documentation!
 ====================================
 
 If you can't find what you need or have suggestions for improvement, don't
-hesitate to open a `new issue on GitHub`_!
+hesitate to open a `new issue on GitHub`_!  
 
-For news and discussions please check out our `G+ OAuthLib community`_.
+Check out :doc:`error_reporting` for details on how to be an awesome bug reporter.
+
+For news and discussions please head over to our `G+ OAuthLib community`_.
 
 .. _`new issue on GitHub`: https://github.com/idan/oauthlib/issues/new
 .. _`G+ OAuthLib community`: https://plus.google.com/communities/101889017375384052571
@@ -18,9 +20,11 @@ For news and discussions please check out our `G+ OAuthLib community`_.
    :maxdepth: 1
 
    installation
-   feature_matrix
    faq
+   feature_matrix
+   error_reporting
    contributing
+   release_process
    oauth_1_versus_oauth_2
 
 .. toctree::
diff --git a/docs/oauth2/grants/grants.rst b/docs/oauth2/grants/grants.rst
index 1018d55..95d3ffe 100644
--- a/docs/oauth2/grants/grants.rst
+++ b/docs/oauth2/grants/grants.rst
@@ -9,6 +9,7 @@ Grant types
     implicit
     password
     credentials
+    jwt
 
 Grant types are what make OAuth 2 so flexible. The Authorization Code grant is
 very similar to OAuth 1 (with less crypto), the Implicit grant serves less
diff --git a/docs/oauth2/tokens/jwt.rst b/docs/oauth2/grants/jwt.rst
index 87aed11..87aed11 100644
--- a/docs/oauth2/tokens/jwt.rst
+++ b/docs/oauth2/grants/jwt.rst
diff --git a/docs/oauth2/tokens/tokens.rst b/docs/oauth2/tokens/tokens.rst
index b565c6b..f0adc97 100644
--- a/docs/oauth2/tokens/tokens.rst
+++ b/docs/oauth2/tokens/tokens.rst
@@ -23,5 +23,4 @@ setting ``OAUTHLIB_STRICT_TOKEN_TYPE`` in the environment.
 
     bearer
     saml
-    jwt
     mac
diff --git a/docs/release_process.rst b/docs/release_process.rst
new file mode 100644
index 0000000..aab97c4
--- /dev/null
+++ b/docs/release_process.rst
@@ -0,0 +1,53 @@
+Release process
+===============
+
+OAuthLib has got to a point where quite a few libraries and users depend on it.
+Because of this a more careful release procedure will be introduced to make
+sure all these lovely projects don't suddenly break.
+
+When approaching a release we will run the unittests for a set of downstream
+libraries using the unreleased version of OAuthLib. If OAuthLib is the cause of
+failing tests we will either
+
+1. Find a way to introduce the change without breaking downstream. However,
+   this is not always the best long term option.
+
+2. Report the breaking change in the affected projects issue tracker or through
+   Github mentions in a "master" issue on OAuthLib if many projects are
+   affected.
+
+Ideally, this process will allow rapid and graceful releases but in the case of
+downstream projects remaining in a broken stage for long we will simply advice
+they lock the oauthlib version in ``setup.py`` and release anyway.
+
+Unittests might not be enough and as an extra measure we will create an
+OAuthLib release issue on Github at least 2 days prior to release detailing the
+changes and pings the primary contacts for each downstream project.  Please
+respond within those 2 days if you have major concerns. 
+
+How to get on the notifcations list
+-----------------------------------
+
+Which projects and the instructions for testing each will be defined in
+OAuthLibs ``Makefile``.  To add your project, simply open a pull request or
+notify that you would like to be added by opening a github issue.
+Please also include github users which can be addressed in Github mentions
+as primary contacts for the project.
+
+When is the next release?
+-------------------------
+
+Releases have been sporadic at best and I don't think that will change soon.
+However, if you think it's time for a new release don't hesitate to open a 
+new issue asking about it.
+
+A note on versioning
+--------------------
+
+Historically OAuthLib has not been very good at semantic versioning but that
+will change after the 1.0.0 release due late 2014. After that poing any major
+digit release (e.g. 2.0.0) may introduce non backwards compatible changes.
+Minor point (1.1.0) releases will introduce non API breaking new features and
+changes. Bug releases (1.0.1) will include minor fixes that needs to be
+released quickly (e.g. after a bigger release unintentionally introduced a
+bug).