Add documentation around oauth2client deprecation (#165)

Author: Jon Wayne Parrott

docs/index.rst

@@ -22,6 +22,8 @@ also provides integration with several HTTP libraries.
   :mod:`urllib3 <google.auth.transport.urllib3>`, and
   :mod:`gRPC <google.auth.transport.grpc>`.
 
+.. note:: ``oauth2client`` was recently deprecated in favor of this library. For more details on the deprecation, see :doc:`oauth2client-deprecation`.
+
 Installing
 ----------
 

docs/oauth2client-deprecation.rst

@@ -0,0 +1,117 @@
+:orphan:
+
+oauth2client deprecation
+========================
+
+This page is intended for existing users of the `oauth2client`_ who want to
+understand the reasons for its deprecation and how this library relates to
+``oauth2client``.
+
+.. _oauth2client: https://github.com/google/oauth2client
+
+Reasons for deprecation
+-----------------------
+
+#. Lack of ownership: ``oauth2client`` has lacked a definitive owner since
+   around 2013.
+#. Fragile and ad-hoc design: ``oauth2client`` is the result of several years
+   of ad-hoc additions and organic, uncontrolled growth. This has led to a
+   library that lacks overall design and cohesion. The convoluted class
+   hierarchy is a symptom of this.
+#. Lack of a secure, thread-safe, and modern transport: ``oauth2client`` is
+   inextricably dependent on `httplib2`_. ``httplib2`` is largely unmaintained
+   (although recently there are a small group of volunteers attempting to
+   maintain it).
+#. Lack of clear purpose and goals: The library is named "oauth2client" but is
+   actually a pretty poor OAuth 2.0 client and does a lot of things that have
+   nothing to do with OAuth and its related RFCs.
+
+.. _httplib2: https://github.com/httplib2/httplib2
+
+We originally planned to address these issues within ``oauth2client``, however,
+we determined that the number of breaking changes needed would be absolutely
+untenable for downstream users. It would essentially involve our users having
+to rewrite significant portions of their code if they needed to upgrade (either
+directly or indirectly through a dependency). Instead, we've chosen to create a
+new replacement library that can live side-by-side with ``oauth2client`` and
+allow users to migrate gradually. We believe that this was the least painful
+option.
+
+Replacement
+-----------
+
+The long-term replacement for ``oauth2client`` is this library,
+``google-auth``. This library addresses the major issues with oauthclient:
+
+#. Clear ownership: google-auth is owned by the teams that maintain the
+   `Cloud Client Libraries`_, `gRPC`_, and the
+   `Code Samples for Google Cloud Platform`_.
+#. Thought-out design: using the lessons learned from ``oauth2client``, we have
+   designed a better module and class hierarchy. The ``v1.0.0`` release of this
+   library should provide long-term API stability.
+#. Modern, secure, and extensible transports: ``google-auth`` supports
+   `urllib3`_, `requests`_, `gRPC`_, and has `legacy support for httplib2`_ to
+   help clients migration. It is transport agnostic and has explicit support
+   for adding new transports.
+#. Clear purpose and goals: ``google-auth`` is explicitly focused on
+   Google-specific authentication, especially the server-to-server (service
+   account) use case.
+ 
+Because we reduced the scope of the library, there are several features in
+``oauth2client`` we intentionally are not supporting in the ``v1.0.0`` release
+of ``google-auth``. This does not mean we are not interested in supporting
+these features, we just didn't feel they should be part of the initial API.
+As downstream users ask for these features we will determine the best way to
+serve those use cases without allowing the library to become a dumping ground.
+ 
+The unsupported features are:
+
+#. Support for obtaining user credentials. While this library has support for
+   using user credentials, there are no provisions in the core library for
+   doing the three-party OAuth 2.0 flow to obtain authorization from a user.
+   Instead, we are opting to provide a separate package that does integration
+   with `oauthlib`_, `google-auth-oauthlib`_. When that library has a stable
+   API, we will consider its inclusion into the core library.
+#. Support for storing credentials. The only credentials type that needs to
+   be stored are user credentials. We have a `discussion thread`_ on what level
+   of support we should do. It's very likely we'll choose to provide an
+   abstract interface for this and leave it up to application to provide
+   storage implementation specific to their use case. It's also very likely
+   that we will also incubate this functionality in the
+   `google-auth-oauthlib`_ library before including it in the core library.
+
+.. _Cloud Client Libraries: https://github.com/googlecloudplatform/google-cloud-python
+.. _gRPC: http://www.grpc.io/
+.. _Code Samples for Google Cloud Platform: https://github.com/googlecloudplatform/python-docs-samples
+.. _urllib3: https://urllib3.readthedocs.io
+.. _requests: http://python-requests.org
+.. _legacy support for httplib2: https://pypi.python.org/pypi/google-auth-httplib2
+.. _oauthlib: https://oauthlib.readthedocs.io
+.. _google-auth-oauthlib: http://google-auth-oauthlib.readthedocs.io/
+.. _discussion thread: https://github.com/GoogleCloudPlatform/google-auth-library-python/issues/33
+
+
+Post-deprecation support
+------------------------
+
+While ``oauth2client`` will not be implementing or accepting any new features,
+the ``google-auth`` team will continue to accept bug reports and fix critical
+bugs. We will make patch releases as necessary. We have no plans to remove the
+library from GitHub or PyPI. Also, we have made sure that the
+`google-api-python-client`_ library supports oauth2client and google-auth and
+will continue to do so indefinitely.
+
+It is important to note that we will not be adding any features, even if an
+external user goes through the trouble of sending a pull request. This policy
+is in place because without it we will perpetuate the circumstances that led
+to ``oauth2client`` being in the semi-unmaintained state it was in previously.
+
+Some old documentation and examples may use ``oauth2client`` instead of
+``google-auth``. We are working to update all of these but it does take a
+significant amount of time. Since we are still iterating on user auth, some
+samples that use user auth will not be updated until we have settled on a final
+interface. If you find any samples you feel should be updated, please
+`file a bug`_.
+
+.. _google-api-python-client: https://github.com/google/google-api-python-client
+.. _file a bug: https://github.com/GoogleCloudPlatform/google-auth-library-python/issues