add upgrading chapter, make docs render again

Chris McDonough

2012-09-13 b72ba1a98ebc6fc6c8d9a11ab1c340b89015e644

add upgrading chapter, make docs render again

 CHANGES.txt

@@ -246,6 +246,12 @@
  * ``registerSettings``, use 
    ``pyramid.config.Configurator.add_settings`` instead.

Documentation
-------------

- Added an "Upgrading Pyramid" chapter to the narrative documentation.  It
  describes how to cope with deprecations and removals of Pyramid APIs.

Dependencies
------------


 docs/changes.rst

@@ -1,3 +1,5 @@
.. _changelog:

:app:`Pyramid` Change History
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


 docs/index.rst

@@ -88,6 +88,7 @@
   narr/advconfig
   narr/extconfig
   narr/scaffolding
   narr/upgrading
   narr/threadlocals
   narr/zca


 docs/latexindex.rst

@@ -85,8 +85,6 @@

   api/authorization
   api/authentication
   api/chameleon_text
   api/chameleon_zpt
   api/config
   api/events
   api/exceptions

 docs/narr/templates.rst

@@ -46,20 +46,6 @@
                                 {'foo':1, 'bar':2}, 
                                 request=request)

.. warning::

   Earlier iterations of this documentation
   (pre-version-1.3) encouraged the application developer to use
   ZPT-specific APIs such as
   :func:`pyramid.chameleon_zpt.render_template_to_response` and
   :func:`pyramid.chameleon_zpt.render_template` to render templates
   directly.  This style of rendering still works, but at least for
   purposes of this documentation, those functions are deprecated.
   Application developers are encouraged instead to use the functions
   available in the :mod:`pyramid.renderers` module to perform
   rendering tasks.  This set of functions works to render templates
   for all renderer extensions registered with :app:`Pyramid`.

The ``sample_view`` :term:`view callable` function above returns a
:term:`response` object which contains the body of the
``templates/foo.pt`` template.  In this case, the ``templates``
@@ -79,12 +65,12 @@
.. warning::

   Only :term:`Chameleon` templates support defining a renderer for a
   template relative to the location of the module where the view
   callable is defined.  Mako templates, and other templating system
   bindings work differently.  In particular, Mako templates use a
   "lookup path" as defined by the ``mako.directories`` configuration
   file instead of treating relative paths as relative to the current
   view module.  See :ref:`mako_templates`.
   template relative to the location of the module where the view callable is
   defined.  Mako templates, and other templating system bindings work
   differently.  In particular, Mako templates use a "lookup path" as defined
   by the ``mako.directories`` configuration file instead of treating
   relative paths as relative to the current view module.  See
   :ref:`mako_templates`.

The path can alternately be a :term:`asset specification` in the form
``some.dotted.package_name:relative/path``. This makes it possible to
@@ -599,10 +585,6 @@
.. code-block:: text

   Hello, world!

If you'd rather use templates directly within a view callable (without
the indirection of using a renderer), see :ref:`chameleon_text_module`
for the API description.

See also :ref:`built_in_renderers` for more general information about
renderers, including Chameleon text renderers.

 docs/narr/upgrading.rst

New file
@@ -0,0 +1,229 @@
Upgrading Pyramid
=================

When a new version of Pyramid is released, it will sometimes deprecate an old
feature or remove an already-deprecated feature.  When features are removed
from Pyramid, applications that depend on those features will begin to break.
This chapter explains how to ensure your Pyramid applications keep working
when you upgrade the Pyramid version you're using.

.. sidebar::   About Release Numbering

   Conventionally, application version numbering in Python is described as
   ``major.minor.micro``.  If your Pyramid version is "1.2.3", it means
   you're running a version of Pyramid with the major version "1", the minor
   version "2" and the micro version "3".  A "major" release is one that
   increments the first-dot number; 2.X.X might follow 1.X.X.  A "minor"
   release is one that increments the second-dot number; 1.3.X might follow
   1.2.X.  A "micro" release is one that increments the third-dot number;
   1.2.3 might follow 1.2.2.  In general, micro releases are "bugfix-only",
   and contain no new features, minor releases contain new features but are
   largely backwards compatible with older versions, and a major release
   indicates a large set of backwards incompatibilities.

The Pyramid core team is conservative when it comes to removing features.  We
don't remove features unnecessarily, but we're human, and we make mistakes
which cause some features to be evolutionary dead ends.  Though we are
willing to support dead-end features for some amount of time, some eventually
have to be removed when the cost of supporting them outweighs the benefit of
keeping them around, because each feature in Pyramid represents a certain
documentation and maintenance burden.

Deprecation and Removal Policy
------------------------------

When a feature is scheduled for removal from Pyramid or any of its official
add-ons, the core development team takes these steps:

- Using the feature will begin to generate a `DeprecationWarning`, indicating
  the version in which the feature became deprecated.

- A note is added to the documentation indicating that the feature is
  deprecated.

- A note is added to the :ref:`changelog` about the deprecation.

When a deprecated feature is eventually removed:

- The feature is removed.

- A note is added to the :ref:`changelog` about the removal.

Features are never removed in *micro* releases.  They are only removed in
minor and major releases.  Deprecated features are kept around for at least
*three* minor releases from the time the feature became deprecated.
Therefore, if a feature is added in Pyramid 1.0, but it's deprecated in
Pyramid 1.1, it will be kept around through all 1.1.X releases, all 1.2.X
releases and all 1.3.X releases.  It will finally be removed in the first
1.4.X release.

Sometimes features are "docs-deprecated" instead of formally deprecated.
This means that the feature will be kept around indefinitely, but it will be
removed from the documentation or a note will be added to the documentation
telling folks to use some other newer feature.  This happens when the cost of
keeping an old feature around is very minimal and the support and
documentation burden is very low.  For example, we might rename a function
that is an API without changing the arguments it accepts.  In this case,
we'll often rename the function, and change the docs to point at the new
function name, but leave around a backwards compatibility alias to the old
function name so older code doesn't break.

"Docs deprecated" features tend to work "forever", meaning that they won't be
removed, and they'll never generate a deprecation warning.  However, such
changes are noted in the :ref:`changelog`, so it's possible to know that you
should change older spellings to newer ones to ensure that people reading
your code can find the APIs you're using in the Pyramid docs.

Consulting the Change History
-----------------------------

Your first line of defense against application failures caused by upgrading
to a newer Pyramid release is always to read the :ref:`changelog`.  to find
the deprecations and removals for each release between the release you're
currently running and the one you wish to upgrade to.  The change history
notes every deprecation within a ``Deprecation`` section and every removal
within a ``Backwards Incompatibilies`` section for each release.

The change history often contains instructions for changing your code to
avoid deprecation warnings and how to change docs-deprecated spellings to
newer ones.  You can follow along with each deprecation explanation in the
change history, simply doing a grep or other code search to your application,
using the change log examples to remediate each potential problem.

.. _testing_under_new_release:

Testing Your Application Under a New Pyramid Release
----------------------------------------------------

Once you've upgraded your application to a new Pyramid release and you've
remediated as much as possible by using the change history notes, you'll want
to run your application's tests (see :ref:`running_tests`) in such a way that
you can see DeprecationWarnings printed to the console when the tests run.

.. code-block:: bash

   $ python -Wd setup.py test -q

The ``-Wd`` argument is an argument that tells Python to print deprecation
warnings to the console.  Note that the ``-Wd`` flag is only required for
Python 2.7 and better: Python versions 2.6 and older print deprecation
warnings to the console by default.  See `the Python -W flag documentation
<http://docs.python.org/using/cmdline.html#cmdoption-W>`_ for more
information.

As your tests run, deprecation warnings will be printed to the console
explaining the deprecation and providing instructions about how to prevent
the deprecation warning from being issued.  For example:

.. code-block:: text

   $ python -Wd setup.py test -q
   # .. elided ...
   running build_ext
   /home/chrism/projects/pyramid/env27/myproj/myproj/views.py:3: DeprecationWarning: static: The "pyramid.view.static" class is deprecated as of Pyramid 1.1; use the "pyramid.static.static_view" class instead with the "use_subpath" argument set to True.
     from pyramid.view import static
   .
   ----------------------------------------------------------------------
   Ran 1 test in 0.014s
   
   OK

In the above case, it's line #3 in the ``myproj.views`` module (``from
pyramid.view import static``) that is causing the problem:

.. code-block:: python
   :linenos:

    from pyramid.view import view_config

    from pyramid.view import static
    myview = static('static', 'static')

The deprecation warning tells me how to fix it, so I can change the code to
do things the newer way:

.. code-block:: python
   :linenos:

    from pyramid.view. import view_config

    from pyramid.static import static_view
    myview = static_view('static', 'static', use_subpath=True)

When I run the tests again, the deprecation warning is no longer printed to
my console:

.. code-block:: text

   $ python -Wd setup.py test -q
   # .. elided ...
   running build_ext
   .
   ----------------------------------------------------------------------
   Ran 1 test in 0.014s
   
   OK


My Application Doesn't Have Any Tests or Has Few Tests
------------------------------------------------------

If your application has no tests, or has only moderate test coverage, running
tests won't tell you very much, because the Pyramid codepaths that generate
deprecation warnings won't be executed.

In this circumstance, you can start your application interactively under a
server run with the ``PYTHONWARNINGS`` environment variable set to
``default``.  On UNIX, you can do that via:

.. code-block:: bash

   $ PYTHONWARNINGS=default bin/pserve development.ini

On Windows, you need to issue two commands:

.. code-block:: bash

   C:\> set PYTHONWARNINGS=default
   C:\> Scripts/pserve.exe development.ini

At this point, it's ensured that deprecation warnings will be printed to the
console whenever a codepath is hit that generates one.  You can then click
around in your application interactively to try to generate them, and
remediate as explained in :ref:`testing_under_new_release`.

See `the PYTHONWARNINGS environment variable documentation
<http://docs.python.org/using/cmdline.html#envvar-PYTHONWARNINGS>`_ or `the
Python -W flag documentation
<http://docs.python.org/using/cmdline.html#cmdoption-W>`_ for more
information.

Upgrading to the Very Latest Pyramid Release
--------------------------------------------

When you upgrade your application to the very most recent Pyramid release,
it's advisable to upgrade step-wise through each most recent minor release,
beginning with the one that you know your application currently runs under,
and ending on the most recent release.  For example, if your application is
running in production on Pyramid 1.2.1, and the most recent Pyramid 1.3
release is Pyramid 1.3.3, and the most recent Pyramid release is 1.4.4, it's
advisable to do this:

- Upgrade your environment to the most recent 1.2 release.  For example, the
  most recent 1.2 release might be 1.2.3, so upgrade to it.  Then run your
  application's tests under 1.2.3 as described in
  :ref:`testing_under_new_release`.  Note any deprecation warnings and
  remediate.

- Upgrade to the most recent 1.3 release, 1.3.3.  Run your application's
  tests, note any deprecation warnings and remediate.

- Upgrade to 1.4.4.  Run your application's tests, note any deprecation
  warnings and remediate.

If you skip testing your application under each minor release (for example if
you upgrade directly from 1.2.1 to 1.4.4), you might miss a deprecation
warning and waste more time trying to figure out an error caused by a feature
removal than it would take to upgrade stepwise through each minor release.



 pyramid/config/factories.py

@@ -184,7 +184,7 @@

        .. warning::

           This method has been deprecated as of Pyramid 1.4.
           This method has been docs-deprecated as of Pyramid 1.4.
           :meth:`pyramid.config.Configurator.add_request_method` should be
           used instead.