From 7f4325d209b8809c9f9c531c8a20b513ca4740ab Mon Sep 17 00:00:00 2001 From: Maxime Helias Date: Mon, 9 Mar 2020 10:18:12 +0100 Subject: [PATCH] Add an explain section to update symfony recipes --- setup/_update_recipes.rst.inc | 38 +++++++++++++++++++++++++++++++++++ setup/upgrade_major.rst | 6 ++++-- setup/upgrade_minor.rst | 38 +---------------------------------- 3 files changed, 43 insertions(+), 39 deletions(-) create mode 100644 setup/_update_recipes.rst.inc diff --git a/setup/_update_recipes.rst.inc b/setup/_update_recipes.rst.inc new file mode 100644 index 00000000000..da963380ce1 --- /dev/null +++ b/setup/_update_recipes.rst.inc @@ -0,0 +1,38 @@ +3) Updating Recipes +------------------- + +Over time - and especially when you upgrade to a new version of a library - an +updated version of the :ref:`recipe ` may be available. +These updates are usually minor - e.g. new comments in a configuration file - but +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 + + 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`_. + +.. _`SymfonyCasts Symfony 5 Upgrade Tutorial`: https://symfonycasts.com/screencast/symfony5-upgrade diff --git a/setup/upgrade_major.rst b/setup/upgrade_major.rst index 9c51834e577..b1fa6690a03 100644 --- 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,7 +178,9 @@ Next, use Composer to download new versions of the libraries: .. _upgrade-major-symfony-after: -3) Update your Code to Work with the New Version +.. include:: /setup/_update_recipes.rst.inc + +4) Update your Code to Work with the New Version ------------------------------------------------ In some rare situations, the next major version *may* contain backwards-compatibility diff --git a/setup/upgrade_minor.rst b/setup/upgrade_minor.rst index 4add91c12da..89c83f5c160 100644 --- a/setup/upgrade_minor.rst +++ b/setup/upgrade_minor.rst @@ -91,43 +91,7 @@ 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 ` 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`_. +.. include:: /setup/_update_recipes.rst.inc .. _`Symfony Repository`: https://github.com/symfony/symfony .. _`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