feature #16301 Adding details about new recipes:update command (weaverryan)

This PR was submitted for the 5.4 branch but it was squashed and merged into the 4.4 branch instead.

Discussion
----------

Adding details about new recipes:update command

See: symfony/flex#845

The `versionadded` version may still change if we decide to put this into the 1.x branch.

Commits
-------

11d87ad Adding details about new recipes:update command

Author: wouterj

.doctor-rst.yaml

@@ -88,7 +88,7 @@ whitelist:
         - '.. versionadded:: 1.11' # MakerBundle
         - '.. versionadded:: 1.3' # MakerBundle
         - '.. versionadded:: 1.8' # MakerBundle
-        - '.. versionadded:: 1.6' # Flex in setup/upgrade_minor.rst
+        - '.. versionadded:: 1.18' # Flex in setup/upgrade_minor.rst
         - '0 => 123' # assertion for var_dumper - components/var_dumper.rst
         - '1 => "foo"' # assertion for var_dumper - components/var_dumper.rst
         - '$var .= "Because of this `\xE9` octet (\\xE9),\n";'

performance.rst

@@ -115,10 +115,13 @@ You can configure PHP to use this preload file:
 
     ; php.ini
     opcache.preload=/path/to/project/config/preload.php
-    
+
     ; required for opcache.preload:
     opcache.preload_user=www-data
 
+If this file is missing, run this command to update the Symfony Flex recipe:
+``composer recipes:update symfony/framework-bundle``.
+
 .. _performance-configure-opcache:
 
 Configure OPcache for Maximum Performance

setup/_update_recipes.rst.inc

@@ -9,30 +9,25 @@ it's a good idea to keep your files in sync with the 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
+.. versionadded:: 1.18
 
-    The recipes commands were introduced in Symfony Flex 1.6.
+    The ``recipes:update`` command was introduced in Symfony Flex 1.18.
 
 .. code-block:: terminal
 
+    # choose an outdated recipe to update
+    $ composer recipes:update
+
+    # update a specific recipe
+    $ composer recipes:update symfony/framework-bundle
+
     # 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`_.
-
-.. _`SymfonyCasts Symfony 5 Upgrade Tutorial`: https://symfonycasts.com/screencast/symfony5-upgrade
+The ``recipes:update`` command is smart: it looks at the difference between the
+recipe when you installed it and the latest version. It then creates a patch and
+applies it to your app. If there are any conflicts, you can resolve them like a
+normal ``git`` conflict and commit like normal.