Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Adding details about recipe upgrade system and upgrade improvements #12959

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

Merged
merged 1 commit into from
Jan 26, 2020
Merged

Adding details about recipe upgrade system and upgrade improvements #12959

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -160,6 +160,8 @@ you'll see a Composer error explaining that ``logger`` is not a valid package
name. However, if the application has Symfony Flex installed, that command
installs and enables all the packages needed to use the official Symfony logger.

.. _recipes-description:

This is possible because lots of Symfony packages/bundles define **"recipes"**,
which are a set of automated instructions to install and enable packages into
Symfony applications. Flex keeps tracks of the recipes it installed in a
Expand Down
11 changes: 6 additions & 5 deletions setup/_update_dep_errors.rst.inc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,16 +1,17 @@
Dependency Errors
~~~~~~~~~~~~~~~~~

If you get a dependency error, it may simply mean that you need to upgrade
other Symfony dependencies too. In that case, try the following command:
If you get a dependency error, it may mean that you also need to upgrade
other libraries that are dependencies of the Symfony libraries. To allow
that, pass the ``--with-all-dependencies`` flag:

.. code-block:: terminal

$ composer update "symfony/*" --with-all-dependencies

This updates ``symfony/symfony`` and *all* packages that it depends on, which will
include several other packages. By using tight version constraints in
``composer.json``, you can control what versions each library upgrades to.
This updates ``symfony/*`` and *all* packages that those packages depend on.
By using tight version constraints in ``composer.json``, you can control what
versions each library upgrades to.

If this still doesn't work, your ``composer.json`` file may specify a version
for a library that is not compatible with the newer Symfony version. In that
Expand Down
62 changes: 41 additions & 21 deletions setup/upgrade_major.rst
View file
Open in desktop
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. 3.4.0 to 4.1.0)
Upgrading a Major Version (e.g. 4.4.0 to 5.0.0)
Copy link
Contributor

Choose a reason for hiding this comment

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

Time flies!

===============================================

Every two years, Symfony releases a new major version release (the first number
Expand Down Expand Up @@ -30,12 +30,14 @@ 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. 4.1.0), all deprecated features and
When the major version is released (e.g. 5.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.
3.4.*), you should be able to upgrade without a problem.
``4.4.*``), you should be able to upgrade without a problem. That means that
you should first :doc:`upgrade to the last minor version </setup/upgrade_minor>`
(e.g. 4.4) so that you can see *all* the deprecations.

To help you with this, deprecation notices are triggered whenever you end up
To help you find deprecations, notices are triggered whenever you end up
using a deprecated feature. When visiting your application in the
:ref:`dev environment <configuration-environments>`
in your browser, these notices are shown in the web dev toolbar:
Expand Down Expand Up @@ -96,7 +98,7 @@ done!
.. sidebar:: Using the Weak Deprecations Mode

Sometimes, you can't fix all deprecations (e.g. something was deprecated
in 3.4 and you still need to support 3.3). In these cases, you can still
in 4.4 and you still need to support 4.3). In these cases, you can still
use the bridge to fix as many deprecations as possible and then allow
more of them to make your tests pass again. You can do this by using the
``SYMFONY_DEPRECATIONS_HELPER`` env variable:
Expand Down Expand Up @@ -124,24 +126,50 @@ done!
-----------------------------------------------

Once your code is deprecation free, you can update the Symfony library via
Composer by modifying your ``composer.json`` file:
Composer by modifying your ``composer.json`` file and changing all the libraries
starting with ``symfony/`` to the new major version:

.. code-block:: json
.. code-block:: diff

{
"...": "...",

"require": {
"symfony/symfony": "^4.1",
- "symfony/cache": "4.3.*",
+ "symfony/cache": "4.4.*",
- "symfony/config": "4.3.*",
+ "symfony/config": "4.4.*",
- "symfony/console": "4.3.*",
+ "symfony/console": "4.4.*",
"...": "...",

"...": "A few libraries starting with
symfony/ follow their versioning scheme. You
do not need to update these versions: you can
upgrade them independently whenever you want",
"symfony/monolog-bundle": "^3.5",
},
"...": "..."
"...": "...",
}

Your ``composer.json`` file should also have an ``extra`` block that you will
*also* need to update:

.. code-block:: diff

"extra": {
"symfony": {
"...": "...",
- "require": "4.4.*"
+ "require": "5.0.*"
}
}

Next, use Composer to download new versions of the libraries:

.. code-block:: terminal

$ composer update symfony/symfony
$ composer update symfony/*

.. include:: /setup/_update_dep_errors.rst.inc

Expand All @@ -152,14 +180,6 @@ Next, use Composer to download new versions of the libraries:
3) Update your Code to Work with the New Version
------------------------------------------------

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 :doc:`/setup/flex`.
In some rare situations, the next major version *may* contain backwards-compatibility
breaks. 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.
84 changes: 65 additions & 19 deletions setup/upgrade_minor.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,37 +22,43 @@ There are two steps to upgrading a minor version:
------------------------------------------

The ``composer.json`` file is configured to allow Symfony packages to be
upgraded to patch versions. But, if you would like the packages to be upgraded
to minor versions, check that the version constrains of the Symfony dependencies
are like this:
upgraded to patch versions. But to upgrade to a new minor version, you will
probably need to update the version constraint next to each library starting
``symfony/``. Suppose you are upgrading from Symfony 4.3 to 4.4:

.. code-block:: json
.. code-block:: diff

{
"...": "...",

"require": {
"symfony/cache": "^4.0",
"symfony/config": "^4.0",
"symfony/console": "^4.0",
"symfony/debug": "^4.0",
"symfony/dependency-injection": "^4.0",
"symfony/dotenv": "^4.0",
"...": "..."
- "symfony/cache": "4.3.*",
+ "symfony/cache": "4.4.*",
- "symfony/config": "4.3.*",
+ "symfony/config": "4.4.*",
- "symfony/console": "4.3.*",
+ "symfony/console": "4.4.*",
Copy link
Member

Choose a reason for hiding this comment

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

Are we sure this is the case? (I'm on Windows atm, so I cannot test it)

If I'm reading https://github.com/symfony/skeleton/blob/master/composer.json correctly, the dependencies are actually marked as * and the extra.symfony.require is used to limit the scope to a specific minor version. That would mean you only need to update that value?

Copy link
Member

Choose a reason for hiding this comment

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

Yes ... that's how I've seen it in modern Symfony apps ... but the reader of this document can use any method actually, especially if they are upgrading from very old Symfony versions.

Copy link
Member Author

@weaverryan weaverryan Jan 26, 2020 •
edited by javiereguiluz
Loading

Choose a reason for hiding this comment

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

In practice, when you compose require symfony/something, it will put the X.X.* version constraint in your composer.json file. So... I'm trying to show an example that will look "like" the user's composer.json file. But technically speaking, you're totally right: if they had ^4.0 everywhere, they could upgrade/control the Symfony versions simply by changing extra.symfony.require. But that's not how things currently will look in real apps.

I talked with Nicolas about this, and I think it (the usage the X.X.* format by composer require) was more-or-less an "accidental" by-product of the extra.symfony.require feature

"...": "...",

"...": "A few libraries starting with
symfony/ follow their versioning scheme. You
do not need to update these versions: you can
upgrade them independently whenever you want",
"symfony/monolog-bundle": "^3.5",
},
"...": "...",
}

At the bottom of your ``composer.json`` file, in the ``extra`` block you can
find a data setting for the symfony version. Make sure to also upgrade
this one. For instance, update it to ``4.3.*`` to upgrade to Symfony 4.3:
Your ``composer.json`` file should also have an ``extra`` block that you will
*also* need to update:

.. code-block:: json
.. code-block:: diff

"extra": {
"symfony": {
"allow-contrib": false,
"require": "4.3.*"
"...": "...",
- "require": "4.3.*"
+ "require": "4.4.*"
}
}

Expand All @@ -76,12 +82,52 @@ 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-4.1.md`_)
Every version of Symfony comes with an UPGRADE file (e.g. `UPGRADE-4.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`_.

.. _updating-flex-recipes:

3) Updating Recipes
-------------------

Over time - and especially when you upgrade to a new version of a library - an
updated version of the :ref:`recipe <recipes-description>` may be available.
These updates are usually minor - e.g. new comments in a configuration file - but
it's a good idea to update the core Symfony recipes.

Symfony Flex provides several commands to help upgrade your recipes. Be sure to
commit any unrelated changes you're working on before starting:

.. versionadded:: 1.6

The recipes commands were introduced in Symfony Flex 1.6.

.. code-block:: terminal

# see a list of all installed recipes and which have updates available
$ composer recipes

# see detailed information about a specific recipes
$ composer recipes symfony/framework-bundle

# update a specific recipes
$ composer recipes:install symfony/framework-bundle --force -v

The tricky part of this process is that the recipe "update" does not perform
any intelligent "upgrading" of your code. Instead, **the updates process re-installs
the latest version of the recipe** which means that **your custom code will be
overridden completely**. After updating a recipe, you need to carefully choose
which changes you want, and undo the rest.

.. admonition:: Screencast
:class: screencast

For a detailed example, see the `SymfonyCasts Symfony 5 Upgrade Tutorial`_.

.. _`Symfony Repository`: https://github.com/symfony/symfony
.. _`UPGRADE-4.1.md`: https://github.com/symfony/symfony/blob/4.1/UPGRADE-4.1.md
.. _`UPGRADE-4.4.md`: https://github.com/symfony/symfony/blob/4.4/UPGRADE-4.4.md
.. _`SymfonyCasts Symfony 5 Upgrade Tutorial`: https://symfonycasts.com/screencast/symfony5-upgrade