Merge pull request #8149 from cakephp/add-rector-migration-docs

Add upgrade tool documentation to migration guides

Author: markstory

en/appendices/5-1-migration-guide.rst

@@ -5,6 +5,15 @@ The 5.1.0 release is a backwards compatible with 5.0. It adds new functionality
 and introduces new deprecations. Any functionality deprecated in 5.x will be
 removed in 6.0.0.
 
+Upgrade Tool
+============
+
+The :doc:`upgrade tool </appendices/migration-guides>` provides rector rules for
+automating some of the migration work. Run rector before updating your
+``composer.json`` dependencies::
+
+    bin/cake upgrade rector --rules cakephp51 <path/to/app/src>
+
 Behavior Changes
 ================
 

en/appendices/5-2-migration-guide.rst

@@ -5,6 +5,15 @@ The 5.2.0 release is a backwards compatible with 5.0. It adds new functionality
 and introduces new deprecations. Any functionality deprecated in 5.x will be
 removed in 6.0.0.
 
+Upgrade Tool
+============
+
+The :doc:`upgrade tool </appendices/migration-guides>` provides rector rules for
+automating some of the migration work. Run rector before updating your
+``composer.json`` dependencies::
+
+    bin/cake upgrade rector --rules cakephp52 <path/to/app/src>
+
 Behavior Changes
 ================
 

en/appendices/5-3-migration-guide.rst

@@ -5,6 +5,15 @@ The 5.3.0 release is a backwards compatible with 5.0. It adds new functionality
 and introduces new deprecations. Any functionality deprecated in 5.x will be
 removed in 6.0.0.
 
+Upgrade Tool
+============
+
+The :doc:`upgrade tool </appendices/migration-guides>` provides rector rules for
+automating some of the migration work. Run rector before updating your
+``composer.json`` dependencies::
+
+    bin/cake upgrade rector --rules cakephp53 <path/to/app/src>
+
 Upgrade to PHP 8.2
 ==================
 

en/appendices/migration-guides.rst

@@ -4,6 +4,28 @@ Migration Guides
 Migration guides contain information regarding the new features introduced in
 each version and the migration path between 5.x minor releases.
 
+Upgrade Tool
+============
+
+CakePHP provides an `upgrade tool <https://github.com/cakephp/upgrade>`__ that
+automates many code changes using `Rector <https://getrector.com/>`__. The tool
+has rulesets for each minor version to help automate tedious code changes like
+method renames and signature updates.
+
+To use the upgrade tool::
+
+    # Install the upgrade tool
+    git clone https://github.com/cakephp/upgrade
+    cd upgrade
+    git checkout 5.x
+    composer install --no-dev
+
+    # Run rector with the desired ruleset
+    bin/cake upgrade rector --rules cakephp51 <path/to/app/src>
+
+Run rector before updating your ``composer.json`` dependencies
+to ensure the tool can resolve class names correctly.
+
 .. toctree::
     :maxdepth: 1