Skip to content

Commit 144e5af

Browse files
weaverryanweaverryan
committed
feature #4611 Adding a guide about upgrading (weaverryan)
This PR was submitted for the 2.6 branch but it was merged into the 2.3 branch instead (closes #4611). Discussion ---------- Adding a guide about upgrading | Q | A | ------------- | --- | Doc fix? | no | New docs? | yes | Applies to | 2.6+ | Fixed tickets | #4172 Hi guys! First, the plan is to merge this into 2.6, then backport it to 2.3 (just remove the 2.5 and 2.6 sections about upgrading). I put this together fairly quickly, and I would really like comments. I've been in front of the computer for awhile, so I'm not convinced this is quite as smooth yet as I'd like it to be! Overall, I want to fix the issue of "How to I upgrade". We'll say - just go to this page, and it'll walk you through the steps, and even reassure you that you don't need to make any changes to your code (or, you only need to make these very specific changes). Thanks! Commits ------- 9701e46 Adding missing index/map documents ca1e7df [#4611] A few more tweaks and fixes e6b3f13 Basically copying a section about upgrading other libraries down into the minor version section 8195a66 [#4611] Removing a few entries I meant to remove before 92b4310 [#4611] Making many tweaks thanks to guys like Javier, Wouter, Christian (xabbuh) and Stof f86b9c9 Adding a guide about upgrading
2 parents 01df3e7 + 9701e46 commit 144e5af

File tree

3 files changed

+146
-0
lines changed

3 files changed

+146
-0
lines changed

‎cookbook/index.rst

+1
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ The Cookbook
2828
symfony1
2929
templating/index
3030
testing/index
31+
upgrading
3132
validation/index
3233
web_server/index
3334
web_services/index

‎cookbook/map.rst.inc

+4
Original file line numberDiff line numberDiff line change
@@ -199,6 +199,10 @@
199199
* (email) :doc:`/cookbook/email/testing`
200200
* (form) :doc:`/cookbook/form/unit_testing`
201201

202+
* **Upgrading**
203+
204+
* :doc:`/cookbook/upgrading`
205+
202206
* :doc:`/cookbook/validation/index`
203207

204208
* :doc:`/cookbook/validation/custom_constraint`

‎cookbook/upgrading.rst

+141
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
How to Upgrade Your Symfony Project
2+
===================================
3+
4+
So a new Symfony release has come out and you want to upgrade, great! Fortunately,
5+
because Symfony protects backwards-compatibility very closely, this *should*
6+
be quite easy.
7+
8+
There are two types of upgrades, and both are a little different:
9+
10+
* :ref:`upgrading-patch-version`
11+
* :ref:`upgrading-minor-version`
12+
13+
.. _upgrading-patch-version:
14+
15+
Upgrading a Patch Version (e.g. 2.6.0 to 2.6.1)
16+
-----------------------------------------------
17+
18+
If you're upgrading and only the patch version (the last number) is changing,
19+
then it's *really* easy:
20+
21+
.. code-block:: bash
22+
23+
$ composer update symfony/symfony
24+
25+
That's it! You should not encounter any backwards-compatibility breaks or
26+
need to change anything else in your code. That's because when you started
27+
your project, your ``composer.json`` included Symfony using a constraint
28+
like ``2.6.*``, where only the *last* version number will change when you
29+
update.
30+
31+
You may also want to upgrade the rest of your libraries. If you've done a
32+
good job with your `version constraints`_ in ``composer.json``, you can do
33+
this safely by running:
34+
35+
.. code-block:: bash
36+
37+
$ composer update
38+
39+
But beware. If you have some bad `version constraints`_ in your ``composer.json``,
40+
(e.g. ``dev-master``), then this could upgrade some non-Symfony libraries
41+
to new versions that contain backwards-compatibility breaking changes.
42+
43+
.. _upgrading-minor-version:
44+
45+
Upgrading a Minor Version (e.g. 2.5.3 to 2.6.1)
46+
-----------------------------------------------
47+
48+
If you're upgrading a minor version (where the middle number changes), then
49+
you should also *not* encounter significant backwards compatibility changes.
50+
For details, see our :doc:`/contributing/code/bc`.
51+
52+
However, some backwards-compatibility breaks *are* possible, and you'll learn
53+
in a second how to prepare for them.
54+
55+
There are two steps to upgrading:
56+
57+
:ref:`upgrade-minor-symfony-composer`;
58+
:ref:`upgrade-minor-symfony-code`
59+
60+
.. _`upgrade-minor-symfony-composer`:
61+
62+
1) Update the Symfony Library via Composer
63+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
64+
65+
First, you need to update Symfony by modifying your ``composer.json`` file
66+
to use the new version:
67+
68+
.. code-block:: json
69+
70+
{
71+
"...": "...",
72+
73+
"require": {
74+
"php": ">=5.3.3",
75+
"symfony/symfony": "2.6.*",
76+
"...": "... no changes to anything else..."
77+
},
78+
"...": "...",
79+
}
80+
81+
Next, use Composer to download new versions of the libraries:
82+
83+
.. code-block:: bash
84+
85+
$ composer update symfony/symfony
86+
87+
You may also want to upgrade the rest of your libraries. If you've done a
88+
good job with your `version constraints`_ in ``composer.json``, you can do
89+
this safely by running:
90+
91+
.. code-block:: bash
92+
93+
$ composer update
94+
95+
But beware. If you have some bad `version constraints`_ in your ``composer.json``,
96+
(e.g. ``dev-master``), then this could upgrade some non-Symfony libraries
97+
to new versions that contain backwards-compatibility breaking changes.
98+
99+
.. _`upgrade-minor-symfony-code`:
100+
101+
2) Updating Your Code to Work with the new Version
102+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
103+
104+
In theory, you should be done! However, you *may* need to make a few changes
105+
to your code to get everything working. Additionally, some features you're
106+
using might still work, but might now be deprecated. That's actually ok,
107+
but if you know about these deprecations, you can start to fix them over
108+
time.
109+
110+
Every version of Symfony comes with an UPGRADE file that describes these
111+
changes. Below are links to the file for each version, which you'll need
112+
to read to see if you need any code changes.
113+
114+
.. tip::
115+
116+
Don't see the version here that you're upgrading to? Just find the
117+
UPGRADE-X.X.md file for the appropriate version on the `Symfony Repository`_.
118+
119+
Upgrading to Symfony 2.6
120+
........................
121+
122+
First, of course, update your ``composer.json`` file with the ``2.6`` version
123+
of Symfony as described above in :ref:`upgrade-minor-symfony-composer`.
124+
125+
Next, check the `UPGRADE-2.6`_ document for details about any code changes
126+
that you might need to make in your project.
127+
128+
Upgrading to Symfony 2.5
129+
........................
130+
131+
First, of course, update your ``composer.json`` file with the ``2.5`` version
132+
of Symfony as described above in :ref:`upgrade-minor-symfony-composer`.
133+
134+
Next, check the `UPGRADE-2.5`_ document for details about any code changes
135+
that you might need to make in your project.
136+
137+
.. _`UPGRADE-2.5`: https://github.com/symfony/symfony/blob/2.5/UPGRADE-2.5.md
138+
.. _`UPGRADE-2.6`: https://github.com/symfony/symfony/blob/2.6/UPGRADE-2.6.md
139+
.. _`Symfony Repository`: https://github.com/symfony/symfony
140+
.. _`Composer Package Versions`: https://getcomposer.org/doc/01-basic-usage.md#package-versions
141+
.. _`version constraints`: https://getcomposer.org/doc/01-basic-usage.md#package-versions

0 commit comments

Comments
 (0)