Adding details about recipe upgrade system and upgrade improvements

weaverryan · javiereguiluz · commit 6305e83c738a · 2020-01-26T19:15:36.000+01:00
diff --git a/setup.rst b/setup.rst
@@ -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
diff --git a/setup/_update_dep_errors.rst.inc b/setup/_update_dep_errors.rst.inc
@@ -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
diff --git a/setup/upgrade_major.rst b/setup/upgrade_major.rst
@@ -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)
 ===============================================
 
 Every two years, Symfony releases a new major version release (the first number
@@ -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:
@@ -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:
@@ -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
 
@@ -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.
diff --git a/setup/upgrade_minor.rst b/setup/upgrade_minor.rst
@@ -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.*",
+            "...": "...",
+
+            "...": "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.*"
         }
     }
 
@@ -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
