Merge pull request #5542 from kenjis/fix-docs-upgrade-instruction

docs: improve upgrade instructions

user_guide_src/source/installation/installing_composer.rst

@@ -50,6 +50,8 @@ A sample such installation command, using the default project-root "appstarter":
 
 After installation you should follow the steps in the "Upgrading" section.
 
+.. _app-starter-upgrading:
+
 Upgrading
 ---------
 
@@ -68,7 +70,7 @@ If ``--prefer-source`` doesn't automatically update to pull latest framework sou
 If you used the ``--no-dev`` option when you created the project, it
 would be appropriate to do so here too, i.e., ``composer update --no-dev``.
 
-Read the upgrade instructions, and check designated  ``app/Config`` folders for affected changes.
+Read the :doc:`upgrade instructions <upgrading>`, and check Breaking Changes and Enhancements.
 
 Pros
 ----
@@ -142,15 +144,16 @@ Copy the ``env``, ``phpunit.xml.dist`` and ``spark`` files, from
 You will have to adjust the system path to refer to the vendor one, e.g., ``ROOTPATH . '/vendor/codeigniter4/framework/system'``,
 - the ``$systemDirectory`` variable in **app/Config/Paths.php**
 
+.. _adding-codeigniter4-upgrading:
+
 Upgrading
 ---------
 
 Whenever there is a new release, then from the command line in your project root::
 
     > composer update --prefer-source
 
-Read the upgrade instructions, and check designated
-``app/Config`` folders for affected changes.
+Read the :doc:`upgrade instructions <upgrading>`, and check Breaking Changes and Enhancements.
 
 Pros
 ----

user_guide_src/source/installation/installing_manual.rst

@@ -27,14 +27,14 @@ Setting Up
 
 None
 
+.. _installing-manual-upgrading:
+
 Upgrading
 ---------
 
-Download a new copy of the framework, and then follow the upgrade
-instructions in the release notice or changelog to merge that with your project.
+Download a new copy of the framework, and then replace the ``system`` folder.
 
-Typically, you replace the ``system`` folder, and check designated
-``app/Config`` folders for affected changes.
+Read the :doc:`upgrade instructions <upgrading>`, and check Breaking Changes and Enhancements.
 
 Pros
 ----

user_guide_src/source/installation/upgrade_416.rst

@@ -2,6 +2,12 @@
 Upgrading from 4.1.5 to 4.1.6
 #############################
 
+Please refer to the upgrade instructions corresponding to your installation method.
+
+- :ref:`Composer Installation App Starter Upgrading <app-starter-upgrading>`
+- :ref:`Composer Installation Adding CodeIgniter4 to an Existing Project Upgrading <adding-codeigniter4-upgrading>`
+- :ref:`Manual Installation Upgrading <installing-manual-upgrading>`
+
 .. contents::
     :local:
     :depth: 2
@@ -22,8 +28,8 @@ none.
 Project Files
 *************
 
-Numerous files in the project space (root, app, public, writable) received updates. Due to
-these files being outside of the system scope they will not be changed without your intervention.
+Numerous files in the **project space** (root, app, public, writable) received updates. Due to
+these files being outside of the **system** scope they will not be changed without your intervention.
 There are some third-party CodeIgniter modules available to assist with merging changes to
 the project space: `Explore on Packagist <https://packagist.org/explore/?query=codeigniter4%20updates>`_.
 
@@ -45,7 +51,7 @@ and it is recommended that you merge the updated versions with your application:
 All Changes
 ===========
 
-This is a list of all files in the project space that received changes;
+This is a list of all files in the **project space** that received changes;
 many will be simple comments or formatting that have no effect on the runtime:
 
 * ``app/Config/Filters.php``