Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit c846723

Browse files
wouterjwouterj
committed
Added new recipe on upgrading a major version
1 parent cce3f35 commit c846723

File tree

4 files changed

+114
-0
lines changed

4 files changed

+114
-0
lines changed

‎cookbook/map.rst.inc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -205,6 +205,7 @@
205205

206206
* :doc:`/cookbook/upgrading/patch_version`
207207
* :doc:`/cookbook/upgrading/minor_version`
208+
* :doc:`/cookbook/upgrading/major_version`
208209

209210
* :doc:`/cookbook/validation/index`
210211

‎cookbook/upgrade/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,3 +15,4 @@ There are three types of upgrades, all needing a little different preparation:
1515

1616
/cookbook/upgrade/patch_version
1717
/cookbook/upgrade/minor_version
18+
/cookbook/upgrade/major_version

‎cookbook/upgrade/major_version.rst

Lines changed: 112 additions & 0 deletions
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+
Once in a couple years, Symfony releases a new major version release (the
8+
first number changes). These releases are the trickiest to upgrade, as they are
9+
allowed to contain BC breaks. However, Symfony tries to make this upgrade
10+
process as 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 a lifecycle of a major release, new features are added and method
27+
signatures and public API usages are changed. However, minor versions should
28+
not contain any backwards compatibility changes. It is made sure that there is
29+
a so-called *backwards compatibility layer* (or BC layer). This means that the
30+
old API will still work, while the new feature is used internally. This BC
31+
layer is then marked as *deprecated*, indicating that it will be
32+
removed/changed in the future.
33+
34+
The major version is the only time all existing BC layers are removed. The last
35+
minor version before a new major version (i.e. 2.7 is the last minor version of
36+
the 2 releases, 3.0 is the next version) will trigger deprecation notices when a
37+
BC layer is used.
38+
39+
When visiting your application in the
40+
:doc:`dev environment </cookbook/configuration/environments>` in your browser,
41+
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 high 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.

‎images/cookbook/deprecations-in-profiler.png

45.3 KB
Loading

0 commit comments

Comments
 (0)