Beginnings of upgrade docs.

1 files changed, 42 insertions, 0 deletions

diff --git a/docs/upgrading-2.0.rst b/docs/upgrading-2.0.rst
new file mode 100644
index 000000000..e896633e5
--- /dev/null
+++ b/docs/upgrading-2.0.rst
@@ -0,0 +1,42 @@
+Upgrading to Pyramid 2.0
+========================
+
+Pyramid 2.0 was built to be backwards compatible with the 1.x series, so no
+changes to your application should be necessary.  However, some functionality
+has been deprecated and it is recommended to upgrade from the legacy systems.
+
+.. _upgrade_auth:
+
+Upgrading to a Security Policy
+------------------------------
+
+The authentication and authorization policies of Pyramid 1.x have been merged
+into a single :term:`security policy` in Pyramid 2.0.  Authentication and
+authorization policies will continue to function normally, however they have
+been deprecated and may be removed in upcoming versions.
+
+A security policy should implement
+:interface:`pyramid.interfaces.ISecurityPolicy`.  You can set the security
+policy for your application via the ``security_policy`` parameter in
+:class:`pyramid.config.Configurator` or by calling
+:meth:`pyramid.config.Configurator.set_security_policy`.  If you set a security
+policy, you cannot set a authentication or authorization policy.
+
+``unauthenticated_userid`` and ``authenticated_userid`` have been replaced with
+the ``identify`` method.  This method should return an :term:`identity`, which
+can be an object of any shape, such as a dictionary or an ORM object.  (It can
+also be a simple user ID, as in the legacy authentication policy.)  The
+identity can be accessed via
+:meth:`pyramid.request.Request.authenticated_identity`.  If you're
+using a legacy authentication policy,
+:meth:`pyramid.request.Request.authenticated_identity` will return the result
+of ``authenticated_userid``.
+
+:prop:`pyramid.request.Request.unauthenticated_userid` and
+:prop:`pyramid.request.Request.authenticated_userid` are deprecated but will
+continue to work as normal with legacy policies.  If using a new security
+policy, both properties will return the string representation of the
+:term:`identity`.  :prop:`pyramid.request.Request.effective_principals` is
+also deprecated and will work with legacy policies, but always return a
+one-element list containing the :data:`pyramid.security.Everyone` principal
+when using a security policy, as there is no equivalent in the new