Add an explain section to update symfony recipes

maxhelias · maxhelias · commit a69e82e0842f · 2020-03-09T10:32:26.000+01:00
diff --git a/setup/upgrade_major.rst b/setup/upgrade_major.rst
@@ -84,7 +84,7 @@ Now, you can start fixing the notices:
     OK (10 tests, 20 assertions)
 
     Remaining deprecation notices (6)
-    
+
     The "request" service is deprecated and will be removed in 3.0. Add a type-hint for
     Symfony\Component\HttpFoundation\Request to your controller parameters to retrieve the
     request instead: 6x
@@ -178,9 +178,48 @@ Next, use Composer to download new versions of the libraries:
 
 .. _upgrade-major-symfony-after:
 
-3) Update your Code to Work with the New Version
+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`_.
+
+4) Update your Code to Work with the New Version
 ------------------------------------------------
 
 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.
+
+.. _`SymfonyCasts Symfony 5 Upgrade Tutorial`: https://symfonycasts.com/screencast/symfony5-upgrade
