Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Commit9fb8966

Browse files
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#5111I 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 bridgeCommits-------604ccab Fix formatting error31999db Fixes after review55fcee9 Applied comments99c5075 Fix typo300e8ab Added new recipe on upgrading a major version2b0aee3 Fix little title case mistake6a90c9b Created 'upgrade' cookbook section
2 parentse7c984f +604ccab commit9fb8966

File tree

11 files changed

+243
-145
lines changed

11 files changed

+243
-145
lines changed

‎contributing/code/bc.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
Ourbackwards Compatibility Promise
1+
OurBackwards Compatibility Promise
22
===================================
33

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

‎cookbook/index.rst

Lines changed: 1 addition & 1 deletion
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

Lines changed: 4 additions & 2 deletions
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

Lines changed: 16 additions & 0 deletions
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

Lines changed: 18 additions & 0 deletions
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

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+
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

Lines changed: 64 additions & 0 deletions
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

Lines changed: 26 additions & 0 deletions
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)
[8]ページ先頭
©2009-2025 Movatter.jp