8000 Adding a guide about upgrading by weaverryan · Pull Request #4611 · symfony/symfony-docs · GitHub
[go: up one dir, main page]
Skip to content

Adding a guide about upgrading #4611

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 6 commits into from
Closed

Adding a guide about upgrading #4611

Changes from 1 commit
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
a3bae94
Adding a guide about upgrading
weaverryan Dec 8, 2014
b7e9d09
[#4611] Making many tweaks thanks to guys like Javier, Wouter, Christ…
weaverryan Jan 3, 2015
e2b925f
[#4611] Removing a few entries I meant to remove before
weaverryan Jan 3, 2015
2bee7cc
Basically copying a section about upgrading other libraries down into…
weaverryan Jan 3, 2015
d915526
[#4611] A few more tweaks and fixes
weaverryan Jan 3, 2015
341e530
Adding missing index/map documents
weaverryan Jan 3, 2015
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
[#4611] Making many tweaks thanks to guys like Javier, Wouter, Christ… 
…ian (xabbuh) and Stof
  • Loading branch information
@weaverryan
weaverryan committed Jan 3, 2015
commit b7e9d09efbdc0ea14d766fbc77a710597f0645f8
64 changes: 38 additions & 26 deletions cookbook/upgrading.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,17 @@
How to Upgrade your Symfony Project
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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wonder if we could add a brief paragraph explaining the basics of semver for those unaware of it. Something like this:

Symfony project uses `Semantic Versioning`_ (or *semver* for short) to release its new versions.
This means that Symfony versions are composed of three numbers (``X.Y.X``) with the following
meaning:

* ``X`` is called the **major version** and it's increased when Symfony makes
  incompatible API changes,
* ``Y`` is called the **minor version** and it's increased when Symfony adds new
  features in a backwards-compatible manner,
* ``Z`` is called the **patch version** and it's increased when Symfony makes
  backwards-compatible bug fixes.

In other words, changing the patch or the minor version numbers should be *safe* for
your application, but changing the major version number would require some work to
update the code of your application.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm, that might be good idea, but I think your proposal is way to long for something that's kind of off-topic for this article. What about adding a reference to the release cycle docs, which also explain this?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree with Wouter here.

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

Expand All @@ -15,40 +22,44 @@ then it's *really* easy:

$ composer update symfony/symfony

That's it! You should not encounter any backwards-compatability breaks or
need to change anything else in your code.
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 Symfony project, your ``composer.json`` included Symfony using a constraint
such as ``2.6.*``, where only the *last* version number changes 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 symfony/symfony
$ 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-compability changes.
to new versions that contain backwards-compatibility breaking changes.

.. _upgrading-minor-version:

Upgrading a Minor Version (e.g. 2.5.3 to 2.6.0)
-----------------------------------------------

If you're upgrading a minor version (where the middle number changes), then
you should also *not* encounter significant backwards compability changes.
you should also *not* encounter significant backwards compatibility changes.
For details, see our :doc:`/contributing/code/bc`.

However, some backwards-compability breaks *are* possible, and you'll learn
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:

1. :ref:`upgrade-minor-symfony-composer`;
2. :ref:`upgrade-minor-symfony-code`, which includes instructions for each version.
#. :ref:`upgrade-minor-symfony-composer`;
#. :ref:`upgrade-minor-symfony-code`, which includes instructions for each version.

.. _`upgrade-minor-symfony-composer`:

Update the Symfony Library
~~~~~~~~~~~~~~~~~~~~~~~~~~
Update the Symfony Library via Composer
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

First, you need to update Symfony by modifying your ``composer.json`` to
use the new version:
Expand All @@ -60,13 +71,13 @@ use the new version:

"require": {
"php": ">=5.3.3",
"symfony/symfony": "~2.6.0",
"symfony/symfony": "~2.6.*",
"...": "... no changes to anything else..."
},
"...": "...",
}

Next, update the same as before:
Next, use Composer to download new versions of the libraries:

.. code-block:: bash

Expand All @@ -75,12 +86,12 @@ Next, update the same as before:
Updating a minor version like this should *not* cause any dependency issues,
though it's always possible that an outside library or bundle you're using
didn't support this new version of Symfony at the version you have of that
library. In that case, consult the library: you may need to modify its version
library. In that case, consult the library: you may need to modify its version
in ``composer.json`` and run a full ``composer update``.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure, if that's they way to update your composer.json file. Isn't composer require your/lib "~2.0" the way to go?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

And by the way, why don't we tell the user how to update the Symfony version using the composer require command?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I actually didn't know using composer require like this worked! I just tried it, that's cool. I have a question related to this that I'll post on this thread in a few minutes

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actually, nevermind. I think that using require isn't the best idea for Symfony, because we tell people to use 2.6.*-style requirements, instead of ~2.6, I guess to be a bit more conservative. Using require would - I believe - give us the tilde version. I did sort of re-word this section though. I think we should actually tell people to use composer update to upgrade their libraries. I think if they actually want a full new version of some non-Symfony library that's beyond what they originally put in their composer.json file, then they're on their own to do that (and this would be a common thing to do with Composer). Also, assuming more and more people use composer require to initially add a library, people will have constraints like ~1.2 more and more commonly, which means "update" will allow them patch and minor versions (and it make sense for them to knowingly opt-in if they want to change the major version).


.. _`upgrade-minor-symfony-code`:

Updating your Code to work with the new Version
Updating Your Code to Work with the new Version
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In theory, you should be done! However, you *may* need to make a few changes
Expand All @@ -90,16 +101,22 @@ 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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe we should also mention than in 2.7, you'll see in the Web Debug Toolbar the number of deprecated features that you are using. And that information should also appear in the log files.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's something else if you ask me. We may should create a quick and small "How to prepare for Symfony 3" article in the docs.

This section is about BC breaks without having a BC layer first.

changes. Below are links to the file for each version, along with some other
details.
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 too? Just find the
UPGRADE-X.X.md file for the appropriate version on the `Symfony Repository`_.

Upgrading to Symfony 2.6
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm -1 on these sections, it'll require lots of maintainance work to keep this up to date

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree with Wouter. This would require a lot of work to keep it maintained.

........................

First, of course, update your ``composer.json`` file with the ``2.6`` version
of Symfony as described above in :ref:`upgrade-minor-symfony-composer`.

Check the `UPGRADE-2.6`_ document for details. Highlights:
Next, check the `UPGRADE-2.6`_ document for details about any code changes
that you might need to make in your project.

* If you're using PdoSessionStorage, there was a change in the session schema
that **requires** your session table to be updated. See :doc:`/cookbook/configuration/pdo_session_storage`.
Expand All @@ -114,14 +131,9 @@ 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`.

Check the `UPGRADE-2.5`_ document for details. Highlights:

* This version introduced a new Validator API. But, as long as you're using
PHP 5.3.9 or higher, you can configure Symfony in a way that allows you
to use the new API, but still let the old API work (called ``2.5-bc``).
See the `UPGRADE-2.5-Validator`_ for details.
Next, check the `UPGRADE-2.5`_ document for details about any code changes
that you might need to make in your project.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

After "updating patch version" and "updating minor version", I miss the "updating major version" section.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's a bit early for this, isn't it? "Updating" from 1.4 to 2.0 was completely different to the way updates from 2.7 to 3.0 will be.

.. _`UPGRADE-2.5`: https://github.com/symfony/symfony/blob/2.5/UPGRADE-2.5.md
.. _`UPGRADE-2.5-Validator`: https://github.com/symfony/symfony/blob/2.7/UPGRADE-2.5.md#validator
.. _`UPGRADE-2.6`: https://github.com/symfony/symfony/blob/2.6/UPGRADE-2.6.md
.. _`UPGRADE-2.6-DebugBundle`: https://github.com/symfony/symfony/blob/2.6/UPGRADE-2.6.md#vardumper-and-debugbundle
.. _`Symfony Repository`: https://github.com/symfony/symfony
0