Permalink
Browse files

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
  • Loading branch information...
weaverryan committed Jan 3, 2015
2 parents 01df3e7 + 9701e46 commit 144e5afbfe44e096a0a743f144a07ac1c6c57696
Showing with 146 additions and 0 deletions.
  1. +1 −0 cookbook/index.rst
  2. +4 −0 cookbook/map.rst.inc
  3. +141 −0 cookbook/upgrading.rst
@@ -28,6 +28,7 @@ The Cookbook
symfony1
templating/index
testing/index
upgrading
validation/index
web_server/index
web_services/index
@@ -199,6 +199,10 @@
* (email) :doc:`/cookbook/email/testing`
* (form) :doc:`/cookbook/form/unit_testing`
* **Upgrading**
* :doc:`/cookbook/upgrading`
* :doc:`/cookbook/validation/index`
* :doc:`/cookbook/validation/custom_constraint`
@@ -0,0 +1,141 @@
How to Upgrade Your Symfony Project
===================================
So a new Symfony release has come out and you want to upgrade, great! Fortunately,
because Symfony protects backwards-compatibility very closely, this *should*
be quite easy.
There are two types of upgrades, and both are a little different:
* :ref:`upgrading-patch-version`
* :ref:`upgrading-minor-version`
.. _upgrading-patch-version:
Upgrading a Patch Version (e.g. 2.6.0 to 2.6.1)
-----------------------------------------------
If you're upgrading and only the patch version (the last number) is changing,
then it's *really* easy:
.. code-block:: bash
$ composer update symfony/symfony
That's it! You should not encounter any backwards-compatibility breaks or
need to change anything else in your code. That's because when you started
your project, your ``composer.json`` included Symfony using a constraint
like ``2.6.*``, where only the *last* version number will change when you
update.
You may also want to upgrade the rest of your libraries. If you've done a
good job with your `version constraints`_ in ``composer.json``, you can do
this safely by running:
.. code-block:: bash
$ composer update
But beware. If you have some bad `version constraints`_ in your ``composer.json``,
(e.g. ``dev-master``), then this could upgrade some non-Symfony libraries
to new versions that contain backwards-compatibility breaking changes.
.. _upgrading-minor-version:
Upgrading a Minor Version (e.g. 2.5.3 to 2.6.1)
-----------------------------------------------
If you're upgrading a minor version (where the middle number changes), then
you should also *not* encounter significant backwards compatibility changes.
For details, see our :doc:`/contributing/code/bc`.
However, some backwards-compatibility breaks *are* possible, and you'll learn
in a second how to prepare for them.
There are two steps to upgrading:
:ref:`upgrade-minor-symfony-composer`;
:ref:`upgrade-minor-symfony-code`
.. _`upgrade-minor-symfony-composer`:
1) Update the Symfony Library via Composer
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
First, you need to update Symfony by modifying your ``composer.json`` file
to use the new version:
.. code-block:: json
{
"...": "...",
"require": {
"php": ">=5.3.3",
"symfony/symfony": "2.6.*",
"...": "... no changes to anything else..."
},
"...": "...",
}
Next, use Composer to download new versions of the libraries:
.. code-block:: bash
$ composer update symfony/symfony
You may also want to upgrade the rest of your libraries. If you've done a
good job with your `version constraints`_ in ``composer.json``, you can do
this safely by running:
.. code-block:: bash
$ composer update
But beware. If you have some bad `version constraints`_ in your ``composer.json``,
(e.g. ``dev-master``), then this could upgrade some non-Symfony libraries
to new versions that contain backwards-compatibility breaking changes.
.. _`upgrade-minor-symfony-code`:
2) Updating Your Code to Work with the new Version
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In theory, you should be done! However, you *may* need to make a few changes
to your code to get everything working. Additionally, some features you're
using might still work, but might now be deprecated. That's actually ok,
but if you know about these deprecations, you can start to fix them over
time.
Every version of Symfony comes with an UPGRADE file that describes these
changes. Below are links to the file for each version, which you'll need
to read to see if you need any code changes.
.. tip::
Don't see the version here that you're upgrading to? Just find the
UPGRADE-X.X.md file for the appropriate version on the `Symfony Repository`_.
Upgrading to Symfony 2.6
........................
First, of course, update your ``composer.json`` file with the ``2.6`` version
of Symfony as described above in :ref:`upgrade-minor-symfony-composer`.
Next, check the `UPGRADE-2.6`_ document for details about any code changes
that you might need to make in your project.
Upgrading to Symfony 2.5
........................
First, of course, update your ``composer.json`` file with the ``2.5`` version
of Symfony as described above in :ref:`upgrade-minor-symfony-composer`.
Next, check the `UPGRADE-2.5`_ document for details about any code changes
that you might need to make in your project.
.. _`UPGRADE-2.5`: https://github.com/symfony/symfony/blob/2.5/UPGRADE-2.5.md
.. _`UPGRADE-2.6`: https://github.com/symfony/symfony/blob/2.6/UPGRADE-2.6.md
.. _`Symfony Repository`: https://github.com/symfony/symfony
.. _`Composer Package Versions`: https://getcomposer.org/doc/01-basic-usage.md#package-versions
.. _`version constraints`: https://getcomposer.org/doc/01-basic-usage.md#package-versions

0 comments on commit 144e5af

Please sign in to comment.