Skip to content


Subversion checkout URL

You can clone with
Download ZIP
100644 235 lines (174 sloc) 9.65 KB
54d3e3e @mcdonc add a whatsnew-1.4 document
mcdonc authored
1 .. _upgrading_chapter:
b72ba1a @mcdonc add upgrading chapter, make docs render again
mcdonc authored
3 Upgrading Pyramid
4 =================
c3b9c42 @mcdonc wording
mcdonc authored
6 When a new version of Pyramid is released, it will sometimes deprecate a
7 feature or remove a feature that was deprecated in an older release. When
8 features are removed from Pyramid, applications that depend on those features
9 will begin to break. This chapter explains how to ensure your Pyramid
10 applications keep working when you upgrade the Pyramid version you're using.
b72ba1a @mcdonc add upgrading chapter, make docs render again
mcdonc authored
12 .. sidebar:: About Release Numbering
14 Conventionally, application version numbering in Python is described as
15 ``major.minor.micro``. If your Pyramid version is "1.2.3", it means
16 you're running a version of Pyramid with the major version "1", the minor
17 version "2" and the micro version "3". A "major" release is one that
18 increments the first-dot number; 2.X.X might follow 1.X.X. A "minor"
19 release is one that increments the second-dot number; 1.3.X might follow
20 1.2.X. A "micro" release is one that increments the third-dot number;
21 1.2.3 might follow 1.2.2. In general, micro releases are "bugfix-only",
22 and contain no new features, minor releases contain new features but are
23 largely backwards compatible with older versions, and a major release
24 indicates a large set of backwards incompatibilities.
26 The Pyramid core team is conservative when it comes to removing features. We
27 don't remove features unnecessarily, but we're human, and we make mistakes
28 which cause some features to be evolutionary dead ends. Though we are
29 willing to support dead-end features for some amount of time, some eventually
30 have to be removed when the cost of supporting them outweighs the benefit of
31 keeping them around, because each feature in Pyramid represents a certain
32 documentation and maintenance burden.
34 Deprecation and Removal Policy
35 ------------------------------
37 When a feature is scheduled for removal from Pyramid or any of its official
38 add-ons, the core development team takes these steps:
40 - Using the feature will begin to generate a `DeprecationWarning`, indicating
41 the version in which the feature became deprecated.
43 - A note is added to the documentation indicating that the feature is
44 deprecated.
46 - A note is added to the :ref:`changelog` about the deprecation.
48 When a deprecated feature is eventually removed:
50 - The feature is removed.
52 - A note is added to the :ref:`changelog` about the removal.
54 Features are never removed in *micro* releases. They are only removed in
55 minor and major releases. Deprecated features are kept around for at least
56 *three* minor releases from the time the feature became deprecated.
57 Therefore, if a feature is added in Pyramid 1.0, but it's deprecated in
58 Pyramid 1.1, it will be kept around through all 1.1.X releases, all 1.2.X
59 releases and all 1.3.X releases. It will finally be removed in the first
60 1.4.X release.
62 Sometimes features are "docs-deprecated" instead of formally deprecated.
63 This means that the feature will be kept around indefinitely, but it will be
64 removed from the documentation or a note will be added to the documentation
65 telling folks to use some other newer feature. This happens when the cost of
66 keeping an old feature around is very minimal and the support and
67 documentation burden is very low. For example, we might rename a function
68 that is an API without changing the arguments it accepts. In this case,
69 we'll often rename the function, and change the docs to point at the new
70 function name, but leave around a backwards compatibility alias to the old
71 function name so older code doesn't break.
73 "Docs deprecated" features tend to work "forever", meaning that they won't be
74 removed, and they'll never generate a deprecation warning. However, such
75 changes are noted in the :ref:`changelog`, so it's possible to know that you
76 should change older spellings to newer ones to ensure that people reading
77 your code can find the APIs you're using in the Pyramid docs.
79 Consulting the Change History
80 -----------------------------
82 Your first line of defense against application failures caused by upgrading
83 to a newer Pyramid release is always to read the :ref:`changelog`. to find
84 the deprecations and removals for each release between the release you're
85 currently running and the one you wish to upgrade to. The change history
86 notes every deprecation within a ``Deprecation`` section and every removal
87 within a ``Backwards Incompatibilies`` section for each release.
89 The change history often contains instructions for changing your code to
90 avoid deprecation warnings and how to change docs-deprecated spellings to
91 newer ones. You can follow along with each deprecation explanation in the
92 change history, simply doing a grep or other code search to your application,
93 using the change log examples to remediate each potential problem.
95 .. _testing_under_new_release:
97 Testing Your Application Under a New Pyramid Release
98 ----------------------------------------------------
100 Once you've upgraded your application to a new Pyramid release and you've
101 remediated as much as possible by using the change history notes, you'll want
102 to run your application's tests (see :ref:`running_tests`) in such a way that
103 you can see DeprecationWarnings printed to the console when the tests run.
105 .. code-block:: bash
107 $ python -Wd test -q
109 The ``-Wd`` argument is an argument that tells Python to print deprecation
110 warnings to the console. Note that the ``-Wd`` flag is only required for
111 Python 2.7 and better: Python versions 2.6 and older print deprecation
112 warnings to the console by default. See `the Python -W flag documentation
113 <>`_ for more
114 information.
116 As your tests run, deprecation warnings will be printed to the console
117 explaining the deprecation and providing instructions about how to prevent
118 the deprecation warning from being issued. For example:
120 .. code-block:: text
122 $ python -Wd test -q
123 # .. elided ...
124 running build_ext
1b58346 @mcdonc docs rendering
mcdonc authored
125 /home/chrism/projects/pyramid/env27/myproj/myproj/
126 DeprecationWarning: static: The "pyramid.view.static" class is deprecated
127 as of Pyramid 1.1; use the "pyramid.static.static_view" class instead with
128 the "use_subpath" argument set to True.
b72ba1a @mcdonc add upgrading chapter, make docs render again
mcdonc authored
129 from pyramid.view import static
130 .
131 ----------------------------------------------------------------------
132 Ran 1 test in 0.014s
134 OK
136 In the above case, it's line #3 in the ``myproj.views`` module (``from
137 pyramid.view import static``) that is causing the problem:
139 .. code-block:: python
140 :linenos:
142 from pyramid.view import view_config
144 from pyramid.view import static
145 myview = static('static', 'static')
147 The deprecation warning tells me how to fix it, so I can change the code to
148 do things the newer way:
150 .. code-block:: python
151 :linenos:
153 from pyramid.view. import view_config
155 from pyramid.static import static_view
156 myview = static_view('static', 'static', use_subpath=True)
158 When I run the tests again, the deprecation warning is no longer printed to
159 my console:
161 .. code-block:: text
163 $ python -Wd test -q
164 # .. elided ...
165 running build_ext
166 .
167 ----------------------------------------------------------------------
168 Ran 1 test in 0.014s
170 OK
173 My Application Doesn't Have Any Tests or Has Few Tests
174 ------------------------------------------------------
176 If your application has no tests, or has only moderate test coverage, running
177 tests won't tell you very much, because the Pyramid codepaths that generate
178 deprecation warnings won't be executed.
180 In this circumstance, you can start your application interactively under a
181 server run with the ``PYTHONWARNINGS`` environment variable set to
182 ``default``. On UNIX, you can do that via:
184 .. code-block:: bash
186 $ PYTHONWARNINGS=default bin/pserve development.ini
188 On Windows, you need to issue two commands:
190 .. code-block:: bash
192 C:\> set PYTHONWARNINGS=default
193 C:\> Scripts/pserve.exe development.ini
195 At this point, it's ensured that deprecation warnings will be printed to the
196 console whenever a codepath is hit that generates one. You can then click
197 around in your application interactively to try to generate them, and
198 remediate as explained in :ref:`testing_under_new_release`.
200 See `the PYTHONWARNINGS environment variable documentation
201 <>`_ or `the
202 Python -W flag documentation
203 <>`_ for more
204 information.
206 Upgrading to the Very Latest Pyramid Release
207 --------------------------------------------
209 When you upgrade your application to the very most recent Pyramid release,
210 it's advisable to upgrade step-wise through each most recent minor release,
211 beginning with the one that you know your application currently runs under,
212 and ending on the most recent release. For example, if your application is
213 running in production on Pyramid 1.2.1, and the most recent Pyramid 1.3
214 release is Pyramid 1.3.3, and the most recent Pyramid release is 1.4.4, it's
215 advisable to do this:
217 - Upgrade your environment to the most recent 1.2 release. For example, the
218 most recent 1.2 release might be 1.2.3, so upgrade to it. Then run your
219 application's tests under 1.2.3 as described in
220 :ref:`testing_under_new_release`. Note any deprecation warnings and
221 remediate.
223 - Upgrade to the most recent 1.3 release, 1.3.3. Run your application's
224 tests, note any deprecation warnings and remediate.
226 - Upgrade to 1.4.4. Run your application's tests, note any deprecation
227 warnings and remediate.
229 If you skip testing your application under each minor release (for example if
230 you upgrade directly from 1.2.1 to 1.4.4), you might miss a deprecation
231 warning and waste more time trying to figure out an error caused by a feature
232 removal than it would take to upgrade stepwise through each minor release.
Something went wrong with that request. Please try again.