migrations/54-60/compat-plugin update (#548)

* migrations/54-60/compat-plugin update

Update is caused by [joomla-cms/pull/46324](joomla/joomla-cms#46324) which links
to `migrations/54-60/compat-plugin`.

* Removed four times 'not been released yet' as Joomla 6.0 is released
* Changes title from singular to plural, but not the file name, as it used as link in the PR above.
* Rewritten the main content (the two b/c plugins) from Joomla 6 view.
* Named exactly 'Behaviour - Backward Compatibility 6', as we have also 'Behaviour - Backward Compatibility' plugin.
* Moved DEVELOPER NOTE to the end, as it is a secondary information.
* Added list of PRs for the 'Behaviour - Backward Compatibility 6'.
  * Is this list complete?
  * Is the list useful?
* Added a note for NEW INSTALLATION as we saw the question multiple times,
  even it is not direct related to the migration.
* Merged the given infos from the three deleted and to b/c plugin moved functionality into
  'Removed and Backward Incompatibility' and linked this page.
  * Is the merge correct?
* Line breaks at 120 chars.

* Fixing "during the upgrade process"

* Fixed link

Author: muhme

migrations/54-60/compat-plugin.md

@@ -2,56 +2,55 @@
 sidebar_position: 5
 ---
 
-Compatibility Plugin
-====================
-
-:::tip[Developer Note]
-  Since this version of Joomla has not been released yet, this page can change anytime.
-:::
-
-:::warning[Developer Note]
-  Heads-up, don't create a plugin as `behaviour` plugin because it's possible that this group get removed at some point.
-:::
-
-## Joomla 5 Compatibility Plugin
-
-As part of Joomla! 5.0 a plugin was introduced which enhance backward compatibility between Joomla 5 and 4. 
-Please check the [Backward Compatibility Plugin](https://manual.joomla.org/migrations/44-50/compat-plugin.md) for more details.
-
-For more detail check [Compatibility Plugin Joomla! 5.0](https://manual.joomla.org/migrations/44-50/compat-plugin).
+Compatibility Plugins
+=====================
 
 ## Joomla 6 Compatibility Plugin
 
-In Joomla! 6.0 the Compatibility Plugin introduced in Joomla! 5.0 will be replaced by a new plugin
-called "Behaviour - Backward Compatibility 6".
+The **‘Behaviour – Backward Compatibility 6’** plugin is essential for the migration from Joomla! 5.4 to 6.x.
+
+In Joomla 5.4, this plugin is installed and enabled by default, but it does not perform any actions.
+Its presence ensures that when the site is upgraded to Joomla 6, the updated code can run immediately,
+and any third-party extensions requiring the plugin to be enabled in Joomla 6 will not cause the update to fail.
 
-Despite the warning about the potential removal of the `behaviour` plugin type, this compatibility plugin still uses
-this type to ensure it loads before any other plugin, as this is critical for backward compatibility functionality.
+As a `behaviour`-type plugin, it loads before any other plugin —
+a critical requirement for ensuring backward compatibility.
 
-### CMS BaseApplication and CLI Classes
+For upgrades from Joomla! 5.4 to Joomla! 6.x, it is mandatory that this plugin is both installed and enabled.
+To review which backward compatibility cases have been removed, see
+[Removed and Backward Incompatibility](../removed-backward-incompatibility).
 
-- PR's:
-  - https://github.com/joomla/joomla-cms/pull/42884
-  - https://github.com/joomla/joomla-cms/pull/44926
-- Description: Any reference to the class `\Joomla\CMS\Application\BaseApplication` and `\Joomla\CMS\Application\CliApplication` with the respective CLI input classes should be replaced with the namespace `\Joomla\Application`. Cli apps should be replaced by console plugins.
+:::tip NEW INSTALLATIONS
+For new Joomla! 6.0 installations, the **‘Behaviour – Backward Compatibility 6’**
+plugin is installed but disabled by default.
+:::
 
-### `JPATH_PLATFORM` Constant
+Related PRs are:
+* [45336](https://github.com/joomla/joomla-cms/pull/45336)
+    Introduce Joomla 6.0 compatibility plugin
+* [45371](https://github.com/joomla/joomla-cms/pull/45371)
+    Add compat6 behaviour plugin to 5.4 so it is available and enabled when updating to 6.x.
+* [45480](https://github.com/joomla/joomla-cms/pull/45480)
+    Introduce Joomla 6.0 compatibility plugin
+* [45493](https://github.com/joomla/joomla-cms/pull/45493)
+    Add pre-update checks for backward compatibility plugins for update to Joomla 6
+* [45525](https://github.com/joomla/joomla-cms/pull/45525)
+    Add compat6 behaviour plugin to 5.4 with enabled options
+* [45973](https://github.com/joomla/joomla-cms/pull/45973)
+    Don't insert duplicate records in update SQL scripts when they are executed multiple times
+
+:::warning DEVELOPER NOTE
+Avoid creating your own plugin within the *Behaviour* group, as this group may be removed in a future release.
+:::
 
-- PR: https://github.com/joomla/joomla-cms/pull/44638
-- File: All bootstrapping files
-- Description: The `JPATH_PLATFORM` is an old constant and should not be used if the Joomla core got correctly bootstrapped. Change your checks to `_JEXEC`
-```php
-// Old:
-\defined('JPATH_PLATFORM') or die;
+## Joomla 5 Compatibility Plugin
 
-// New:
-\defined('_JEXEC') or die;
-```
+Introduced in Joomla! 5.0, the **‘Behaviour – Backward Compatibility’**
+plugin improves compatibility between Joomla 5 and 4.
 
-### CMS Input Package
+When upgrading from Joomla! 5.4 to Joomla! 6.x, this plugin must be disabled before starting the upgrade.
+If the site fails to load after disabling it in Joomla 5.4, simply re-enable the plugin to restore functionality.
+The errors should then be investigated and resolved while still running Joomla 5.4, before attempting the upgrade again.
 
-- PR's: 
-  - https://github.com/joomla/joomla-cms/pull/42805
-  - https://github.com/joomla/joomla-cms/pull/42890
-  - https://github.com/joomla/joomla-cms/pull/44925
-- Description: Any reference to the class `\Joomla\CMS\Input\Input` or the other classes in that namespace should be replaced with the [framework `Input`](https://github.com/joomla-framework/input) package and the namespace `\Joomla\Input`. The packages can be used nearly interchangeably.
+This approach ensures that any incompatibilities are detected and fixed safely in the Joomla 5.4 environment,
+avoiding partial or corrupted upgrades that may occur if the site crashes during the upgrade process.

migrations/54-60/new-deprecations.md

@@ -5,10 +5,6 @@ sidebar_position: 2
 # New deprecations
 ================
 
-:::tip[Developer Note]
-  Since this version of Joomla has not been released yet, this page can change anytime.
-:::
-
 All the new deprecations that should be aware of and what you should now be using instead.
 
 ## Class Deprecations

migrations/54-60/new-features.md

@@ -5,10 +5,6 @@ sidebar_position: 1
 New Features
 ============
 
-:::tip[Developer Note]
-  Since this version of Joomla has not been released yet, this page can change anytime.
-:::
-
 All the new features that have been added to this version.
 Any changes in best practice.
 

migrations/54-60/removed-backward-incompatibility.md

@@ -5,10 +5,6 @@ sidebar_position: 3
 Removed and Backward Incompatibility
 ====================================
 
-:::tip[Developer Note]
-  Since this version of Joomla has not been released yet, this page can change anytime.
-:::
-
 All the deprecated features than have now been removed and any backward incompatibilities.
 There should be an explanation of how to mitigate the removals / changes.
 
@@ -67,7 +63,13 @@ echo $article->title;
 - PR's: 
   - https://github.com/joomla/joomla-cms/pull/42805
   - https://github.com/joomla/joomla-cms/pull/42890
-- Description: The CMS Input namespace `\Joomla\CMS\Input` has been removed. The CMS core code has switched the code to the Framework Input library with the namespace `\Joomla\Input`, which is very much a drop-in replacement. This is especially of relevance if you are using the MVC classes, which now use the framework class. Make sure that your code imports the correct class.
+  - https://github.com/joomla/joomla-cms/pull/44925
+- Description: The CMS Input namespace `\Joomla\CMS\Input` has been removed.
+  It is only available if the 'Behaviour - Backward Compatibility 6' plugin is enabled.
+  The CMS core code has switched the code to the Framework Input
+  [framework `Input`](https://github.com/joomla-framework/input) package with the namespace `\Joomla\Input`,
+  which is very much a drop-in replacement. This is especially of relevance if you are using the MVC classes,
+  which now use the framework class. Make sure that your code imports the correct class.
 
 ## UTC Used Instead of GMT
 
@@ -190,7 +192,7 @@ if ($app instanceof \Joomla\CMS\Application\ConsoleApplication) {
 	- File moved from `media/legacy/js` to `media/vendor/jquery/js`
 	- PR: https://github.com/joomla/joomla-cms/pull/45020
 
-## CMS Filesystem Package Moved to the Backward Compatibility Plugin
+## CMS Filesystem Package Moved to the 'Behaviour - Backward Compatibility 6' Plugin
 
 - PR: https://github.com/joomla/joomla-cms/pull/44240
 - Folder: libraries/src/Filesystem
@@ -279,19 +281,32 @@ Factory::getApplication()->bootComponent('actionlogs')->getMVCFactory()
 - PR: https://github.com/joomla/joomla-cms/pull/43794
 - Description: The classes `\Joomla\CMS\Adapter\Adapter` and `\Joomla\CMS\Adapter\AdapterInstance` have been removed without replacement.
 
-## Remove deprecated BaseApplication and CLI classes
-- PR: https://github.com/joomla/joomla-cms/pull/42884
+## Remove CMS BaseApplication and CLI classes
+- PRs
+  - https://github.com/joomla/joomla-cms/pull/42884
+  - https://github.com/joomla/joomla-cms/pull/44926
 - Files: `libraries/src/Application/BaseApplication.php`, `libraries/src/Application/CLI.php`
 - Description: These legacy classes have been removed.  
-  Use `\Joomla\CMS\Application\ConsoleApplication` or framework equivalents instead.  
+  Any reference to the class `\Joomla\CMS\Application\BaseApplication` and `\Joomla\CMS\Application\CliApplication`
+  with the respective CLI input classes should be replaced with the namespace `\Joomla\Application`.
+  Cli apps should be replaced by console plugins.
+  Use `\Joomla\CMS\Application\ConsoleApplication` or framework equivalents instead.
   **(more detail needed: migration examples)**
 
-## Move JPATH_PLATFORM constant to compat plugin
+## Remove JPATH_PLATFORM Constant
 - PR: https://github.com/joomla/joomla-cms/pull/44638
+- Files: All bootstrapping files
 - Description: The `JPATH_PLATFORM` constant is no longer globally defined.  
-  It is only available if the Backward Compatibility plugin is enabled.  
-  Extensions should avoid using this constant.  
-  **(more detail needed: code examples and alternatives)**
+  It is only available if the 'Behaviour - Backward Compatibility 6' plugin is enabled.
+  Extensions should avoid using this constant.
+  Change your checks to `_JEXEC`:
+  ```php
+  // Old:
+  \defined('JPATH_PLATFORM') or die;
+
+  // New:
+  \defined('_JEXEC') or die;
+  ```
 
 ## Remove fetchExtensionCompatibility in UpdateController
 - PR: https://github.com/joomla/joomla-cms/pull/45436