Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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