Skip to content

Upgrading the upgrade docs #8796

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.

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

Merged
merged 1 commit into from
Nov 30, 2017
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
2 changes: 2 additions & 0 deletions setup/flex.rst
Original file line number Diff line number Diff line change
Expand Up @@ -124,6 +124,8 @@ Symfony application by executing the following command:
recommended since Symfony 3.3. Use the Composer ``create-project`` command
instead.

.. _upgrade-to-flex:

Upgrading Existing Applications to Flex
---------------------------------------

Expand Down
30 changes: 15 additions & 15 deletions setup/upgrade_major.rst
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
.. index::
single: Upgrading; Major Version

Upgrading a Major Version (e.g. 2.7.0 to 3.0.0)
Upgrading a Major Version (e.g. 3.4.0 to 4.0.0)
===============================================

Every two years, Symfony releases a new major version release (the first number
Expand Down Expand Up @@ -30,10 +30,10 @@ backwards incompatible changes. To accomplish this, the "old" (e.g. functions,
classes, etc) code still works, but is marked as *deprecated*, indicating that
it will be removed/changed in the future and that you should stop using it.

When the major version is released (e.g. 3.0.0), all deprecated features and
When the major version is released (e.g. 4.0.0), all deprecated features and
functionality are removed. So, as long as you've updated your code to stop
using these deprecated features in the last version before the major (e.g.
2.8.*), you should be able to upgrade without a problem.
3.4.*), you should be able to upgrade without a problem.

To help you with this, deprecation notices are triggered whenever you end up
using a deprecated feature. When visiting your application in the
Expand Down Expand Up @@ -95,7 +95,7 @@ done!
.. sidebar:: Using the Weak Deprecations Mode

Sometimes, you can't fix all deprecations (e.g. something was deprecated
in 2.8 and you still need to support 2.7). In these cases, you can still
in 3.4 and you still need to support 3.3). In these cases, you can still
use the bridge to fix as many deprecations as possible and then switch
to the weak test mode to make your tests pass again. You can do this by
using the ``SYMFONY_DEPRECATIONS_HELPER`` env variable:
Expand All @@ -113,12 +113,6 @@ done!

(you can also execute the command like ``SYMFONY_DEPRECATIONS_HELPER=weak phpunit``).

.. tip::

Some members of the Symfony Community have developed a tool called
`Symfony-Upgrade-Fixer`_ which automatically fixes some of the most common
deprecations found when upgrading from Symfony 2 to Symfony 3.

.. _upgrade-major-symfony-composer:

2) Update to the New Major Version via Composer
Expand All @@ -133,7 +127,7 @@ Composer by modifying your ``composer.json`` file:
"...": "...",

"require": {
"symfony/symfony": "3.0.*",
"symfony/symfony": "^4.0",
},
"...": "..."
}
Expand All @@ -153,10 +147,16 @@ Next, use Composer to download new versions of the libraries:
3) Update your Code to Work with the New Version
------------------------------------------------

There is a good chance that you're done now! However, the next major version
*may* also contain new BC breaks as a BC layer is not always a possibility.
Make sure you read the ``UPGRADE-X.0.md`` (where X is the new major version)
included in the Symfony repository for any BC break that you need to be aware
The next major version *may* also contain new BC breaks as a BC layer is not always
a possibility. Make sure you read the ``UPGRADE-X.0.md`` (where X is the new major
version) included in the Symfony repository for any BC break that you need to be aware
of.

4) Updating to the Symfony 4 Flex Directory Structure
-----------------------------------------------------

When upgrading to Symfony 4, you will probably also want to upgrade to the new
Symfony 4 directory structure so that you can take advantage of Symfony Flex.
This takes some work, but is optional. For details, see :ref:`upgrade-to-flex`.

.. _`Symfony-Upgrade-Fixer`: https://github.com/umpirsky/Symfony-Upgrade-Fixer
8 changes: 4 additions & 4 deletions setup/upgrade_minor.rst
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
.. index::
single: Upgrading; Minor Version

Upgrading a Minor Version (e.g. 2.5.3 to 2.6.1)
Upgrading a Minor Version (e.g. 3.3.3 to 3.4.0)
===============================================

If you're upgrading a minor version (where the middle number changes), then
Expand Down Expand Up @@ -30,7 +30,7 @@ to use the new version:
"...": "...",

"require": {
"symfony/symfony": "2.6.*",
"symfony/symfony": "3.4.*",
},
"...": "...",
}
Expand All @@ -55,12 +55,12 @@ to your code to get everything working. Additionally, some features you're
using might still work, but might now be deprecated. While that's just fine,
if you know about these deprecations, you can start to fix them over time.

Every version of Symfony comes with an UPGRADE file (e.g. `UPGRADE-2.7.md`_)
Every version of Symfony comes with an UPGRADE file (e.g. `UPGRADE-3.4.md`_)
included in the Symfony directory that describes these changes. If you follow
the instructions in the document and update your code accordingly, it should be
safe to update in the future.

These documents can also be found in the `Symfony Repository`_.

.. _`Symfony Repository`: https://github.com/symfony/symfony
.. _`UPGRADE-2.7.md`: https://github.com/symfony/symfony/blob/2.7/UPGRADE-2.7.md
.. _`UPGRADE-3.4.md`: https://github.com/symfony/symfony/blob/3.4/UPGRADE-3.4.md
4 changes: 2 additions & 2 deletions setup/upgrade_patch.rst
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
.. index::
single: Upgrading; Patch Version

Upgrading a Patch Version (e.g. 2.6.0 to 2.6.1)
Upgrading a Patch Version (e.g. 3.3.2 to 3.3.3)
===============================================

When a new patch version is released (only the last number changed), it is a
Expand All @@ -15,7 +15,7 @@ version is *really* easy:
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
like ``3.3.*``, where only the *last* version number will change when you
update.

.. tip::
Expand Down