Skip to content

Commit 9fb8966

Browse files
weaverryanweaverryan
committed
feature #5155 Documented upgrading path for a major version (WouterJ)
This PR was merged into the 2.3 branch. Discussion ---------- Documented upgrading path for a major version | Q | A | --- | --- | Doc fix? | no | New docs? | yes | Applies to | all | Fixed tickets | #5059, partially #5111 I feel like there are lots of questions about this topic and nothing has officially been written about it yet. This PR is a first shot at documenting the steps you need to take. I found this one of the hardest things to explain in an easy way. I hope others can improve it a bit :) Todo --- * [x] Add image of toolbar * [x] Add result of PhpUnit bridge Commits ------- 604ccab Fix formatting error 31999db Fixes after review 55fcee9 Applied comments 99c5075 Fix typo 300e8ab Added new recipe on upgrading a major version 2b0aee3 Fix little title case mistake 6a90c9b Created 'upgrade' cookbook section
2 parents e7c984f + 604ccab commit 9fb8966

11 files changed

+243
-145
lines changed

‎contributing/code/bc.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
Our backwards Compatibility Promise
1+
Our Backwards Compatibility Promise
22
===================================
33

44
Ensuring smooth upgrades of your projects is our first priority. That's why

‎cookbook/index.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ The Cookbook
2929
symfony1
3030
templating/index
3131
testing/index
32-
upgrading
32+
upgrade/index
3333
validation/index
3434
web_server/index
3535
web_services/index

‎cookbook/map.rst.inc

+4-2
Original file line numberDiff line numberDiff line change
@@ -207,9 +207,11 @@
207207
* (email) :doc:`/cookbook/email/testing`
208208
* (form) :doc:`/cookbook/form/unit_testing`
209209

210-
* **Upgrading**
210+
* :doc:`/cookbook/upgrade/index`
211211

212-
* :doc:`/cookbook/upgrading`
212+
* :doc:`/cookbook/upgrade/patch_version`
213+
* :doc:`/cookbook/upgrade/minor_version`
214+
* :doc:`/cookbook/upgrade/major_version`
213215

214216
* :doc:`/cookbook/validation/index`
215217

‎cookbook/upgrade/_update_all_packages.rst.inc

+16
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
You may also want to upgrade the rest of your libraries. If you've done a
2+
good job with your `version constraints`_ in ``composer.json``, you can do
3+
this safely by running:
4+
5+
.. code-block:: bash
6+
7+
$ composer update
8+
9+
.. caution::
10+
11+
Beware, if you have some unspecific `version constraints`_ in your
12+
``composer.json`` (e.g. ``dev-master``), this could upgrade some
13+
non-Symfony libraries to new versions that contain backwards-compatibility
14+
breaking changes.
15+
16+
.. _`version constraints`: https://getcomposer.org/doc/01-basic-usage.md#package-versions

‎cookbook/upgrade/index.rst

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
.. index::
2+
single: Upgrading
3+
4+
Upgrading
5+
=========
6+
7+
So a new Symfony release has come out and you want to upgrade, great! Fortunately,
8+
because Symfony protects backwards-compatibility very closely, this *should*
9+
be quite easy.
10+
11+
There are three types of upgrades, all needing a little different preparation:
12+
13+
.. toctree::
14+
:maxdepth: 2
15+
16+
/cookbook/upgrade/patch_version
17+
/cookbook/upgrade/minor_version
18+
/cookbook/upgrade/major_version

‎cookbook/upgrade/major_version.rst

+112
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
.. index::
2+
single: Upgrading; Major Version
3+
4+
Upgrading a Major Version (e.g. 2.7.0 to 3.0.0)
5+
===============================================
6+
7+
Every few years, Symfony releases a new major version release (the first number
8+
changes). These releases are the trickiest to upgrade, as they are allowed to
9+
contain BC breaks. However, Symfony tries to make this upgrade process as
10+
smooth as possible.
11+
12+
This means that you can update most of your code before the major release is
13+
actually released. This is called making your code *future compatible*.
14+
15+
There are a couple of steps to upgrading a major version:
16+
17+
#. :ref:`Make your code deprecation free <upgrade-major-symfony-deprecations>`;
18+
#. :ref:`Update to the new major version via Composer <upgrade-major-symfony-composer>`.
19+
#. :ref:`Update your code to work with the new version <upgrade-major-symfony-after>`
20+
21+
.. _upgrade-major-symfony-deprecations:
22+
23+
1) Make your Code Deprecation Free
24+
----------------------------------
25+
26+
During the lifecycle of a major release, new features are added and method
27+
signatures and public API usages are changed. However,
28+
:doc:`minor versions </cookbook/upgrade/minor_version>` should not contain any
29+
backwards compatibility changes. To accomplish this, the "old" (e.g. functions,
30+
classes, etc) code still works, but is marked as *deprecated*, indicating that
31+
it will be removed/changed in the future and that you should stop using it.
32+
33+
When the major version is released (e.g. 3.0.0), all deprecated features and
34+
functionality are removed. So, as long as you've updated your code to stop
35+
using these deprecated features in the last version before the major (e.g.
36+
2.8.*), you should be able to upgrade without a problem.
37+
38+
To help you with this, the last minor releases will trigger deprecated notices.
39+
For example, 2.7 and 2.8 trigger deprecated notices. When visiting your
40+
application in the :doc:`dev environment </cookbook/configuration/environments>`
41+
in your browser, these notices are shown in the web dev toolbar:
42+
43+
.. image:: /images/cookbook/deprecations-in-profiler.png
44+
45+
Deprecations in PHPUnit
46+
~~~~~~~~~~~~~~~~~~~~~~~
47+
48+
By default, PHPUnit will handle deprecation notices as real errors. This means
49+
that all tests are aborted because it uses a BC layer.
50+
51+
To make sure this doesn't happen, you can install the PHPUnit bridge:
52+
53+
.. code-block:: bash
54+
55+
$ composer require symfony/phpunit-bridge
56+
57+
Now, your tests execute normally and a nice summary of the deprecation notices
58+
is displayed at the end of the test report:
59+
60+
.. code-block:: text
61+
62+
$ phpunit
63+
...
64+
65+
OK (10 tests, 20 assertions)
66+
67+
Remaining deprecation notices (6)
68+
69+
The "request" service is deprecated and will be removed in 3.0. Add a typehint for
70+
Symfony\Component\HttpFoundation\Request to your controller parameters to retrieve the
71+
request instead: 6x
72+
3x in PageAdminTest::testPageShow from Symfony\Cmf\SimpleCmsBundle\Tests\WebTest\Admin
73+
2x in PageAdminTest::testPageList from Symfony\Cmf\SimpleCmsBundle\Tests\WebTest\Admin
74+
1x in PageAdminTest::testPageEdit from Symfony\Cmf\SimpleCmsBundle\Tests\WebTest\Admin
75+
76+
.. _upgrade-major-symfony-composer:
77+
78+
2) Update to the New Major Version via Composer
79+
-----------------------------------------------
80+
81+
If your code is deprecation free, you can update the Symfony library via
82+
Composer by modifying your ``composer.json`` file:
83+
84+
.. code-block:: json
85+
86+
{
87+
"...": "...",
88+
89+
"require": {
90+
"symfony/symfony": "3.0.*",
91+
},
92+
"...": "...",
93+
}
94+
95+
Next, use Composer to download new versions of the libraries:
96+
97+
.. code-block:: bash
98+
99+
$ composer update symfony/symfony
100+
101+
.. include:: /cookbook/upgrade/_update_all_packages.rst.inc
102+
103+
.. _upgrade-major-symfony-after:
104+
105+
3) Update your Code to Work with the New Version
106+
------------------------------------------------
107+
108+
There is a good chance that you're done now! However, the next major version
109+
*may* also contain new BC breaks as a BC layer is not always a possibility.
110+
Make sure you read the ``UPGRADE-X.0.md`` (where X is the new major version)
111+
included in the Symfony repository for any BC break that you need to be aware
112+
of.

‎cookbook/upgrade/minor_version.rst

+64
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
.. index::
2+
single: Upgrading; Minor Version
3+
4+
Upgrading a Minor Version (e.g. 2.5.3 to 2.6.1)
5+
===============================================
6+
7+
If you're upgrading a minor version (where the middle number changes), then
8+
you should *not* encounter significant backwards compatibility changes. For
9+
details, see the :doc:`Symfony backwards compatibility promise </contributing/code/bc>`.
10+
11+
However, some backwards-compatibility breaks *are* possible and you'll learn in
12+
a second how to prepare for them.
13+
14+
There are two steps to upgrading a minor version:
15+
16+
#. :ref:`Update the Symfony library via Composer <upgrade-minor-symfony-composer>`;
17+
#. :ref:`Update your code to work with the new version <upgrade-minor-symfony-code>`.
18+
19+
.. _`upgrade-minor-symfony-composer`:
20+
21+
1) Update the Symfony Library via Composer
22+
------------------------------------------
23+
24+
First, you need to update Symfony by modifying your ``composer.json`` file
25+
to use the new version:
26+
27+
.. code-block:: json
28+
29+
{
30+
"...": "...",
31+
32+
"require": {
33+
"symfony/symfony": "2.6.*",
34+
},
35+
"...": "...",
36+
}
37+
38+
Next, use Composer to download new versions of the libraries:
39+
40+
.. code-block:: bash
41+
42+
$ composer update symfony/symfony
43+
44+
.. include:: /cookbook/upgrade/_update_all_packages.rst.inc
45+
46+
.. _`upgrade-minor-symfony-code`:
47+
48+
2) Updating your Code to Work with the new Version
49+
--------------------------------------------------
50+
51+
In theory, you should be done! However, you *may* need to make a few changes
52+
to your code to get everything working. Additionally, some features you're
53+
using might still work, but might now be deprecated. While that's just fine,
54+
if you know about these deprecations, you can start to fix them over time.
55+
56+
Every version of Symfony comes with an UPGRADE file (e.g. `UPGRADE-2.7.md`_)
57+
included in the Symfony directory that describes these changes. If you follow
58+
the instructions in the document and update your code accordingly, it should be
59+
safe to update in the future.
60+
61+
These documents can also be found in the `Symfony Repository`_.
62+
63+
.. _`Symfony Repository`: https://github.com/symfony/symfony
64+
.. _`UPGRADE-2.7.md`: https://github.com/symfony/symfony/blob/2.7/UPGRADE-2.7.md

‎cookbook/upgrade/patch_version.rst

+26
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
.. index::
2+
single: Upgrading; Patch Version
3+
4+
Upgrading a Patch Version (e.g. 2.6.0 to 2.6.1)
5+
===============================================
6+
7+
When a new patch version is released (only the last number changed), it is a
8+
release that only contains bug fixes. This means that upgrading to a new patch
9+
version is *really* easy:
10+
11+
.. code-block:: bash
12+
13+
$ composer update symfony/symfony
14+
15+
That's it! You should not encounter any backwards-compatibility breaks or
16+
need to change anything else in your code. That's because when you started
17+
your project, your ``composer.json`` included Symfony using a constraint
18+
like ``2.6.*``, where only the *last* version number will change when you
19+
update.
20+
21+
.. tip::
22+
23+
It is recommended to update to a new patch version as soon as possible, as
24+
important bugs and security leaks may be fixed in these new releases.
25+
26+
.. include:: /cookbook/upgrade/_update_all_packages.rst.inc

0 commit comments

Comments
 (0)