Update upgrading doc

development/development/upgrade.rst

@@ -2,13 +2,11 @@
 Upgrade Guide
 =============
 
-This document outlines changes introduced in different versions of phpBB. These changes may require adjustments to your
-existing custom PHP code or Extension code when upgrading to specific versions from a prior versions of phpBB.
-It is mainly meant to be used by core and Extension developers and does not provide end user documentation for upgrading.
+This guide summarizes code-level changes introduced in various phpBB versions that may require updates to your custom PHP code, extensions, or styles during an upgrade.
 
-Unless explicitly stated otherwise, each version describes the changes compared to the previous major or minor version
-that directly preceded it. For example the upgrade guide for 4.0 will describe the changes compared to 3.3 whereas an upgrade guide
-for 4.1 will describe the changes compared to 4.0.
+It is intended primarily for core developers, extension authors, and style creators. **It does not cover instructions for end users performing a board upgrade.**
+
+Unless otherwise noted, each upgrade entry documents changes relative to the immediately preceding major or minor release.
 
 Contents:
 

development/development/upgrade/400.rst

@@ -2,7 +2,8 @@
 phpBB 3.3 to 4.0
 ================
 
-phpBB 4.0 is a major release that contains backward compatibility breaks and also introduces some deprecations.
+phpBB 4.0 is a major release that includes backward-incompatible changes and new deprecations.
+This guide highlights the most important changes and resources to help extension and style developers adapt their code.
 
 .. contents:: Table of Contents
    :depth: 2
@@ -14,42 +15,56 @@ Basics
 
 PHP
 ---
-The minimum required version of PHP for phpBB 4.0 is ``8.1`` with full support for versions ``8.2`` and ``8.3``.
-PHP code that worked with the supported versions of phpBB 3.3 should work with phpBB 4.0 as well but might require minor adjustments.Recommendation
+phpBB 4.0 requires PHP 8.1 or higher. Most PHP code compatible with phpBB 3.3 should work in phpBB 4.0 with minimal changes,
+but you may need to make adjustments depending on deprecated or changed functionality.
 
 Symfony
 -------
-phpBB 4.0 ships with Symfony 6.4. There are quite a few changes to the standard Symfony version that came with phpBB 3.3.
-The following upgrade guides provides by Symfony might help with resolving some of the issues you might encounter when upgrading
-custom PHP or Extension code for phpBB 4.0:
+phpBB 4.0 uses Symfony 6.4, a significant upgrade from the version bundled with phpBB 3.3. As Symfony introduced breaking
+changes across versions, we recommend reviewing the following Symfony upgrade guides when updating custom code or extensions:
 
 - `Upgrade Symfony from 3.x to 4.0 <https://github.com/symfony/symfony/blob/4.4/UPGRADE-4.0.md>`_
 - `Upgrade Symfony from 4.4 to 5.0 <https://github.com/symfony/symfony/blob/5.4/UPGRADE-5.0.md>`_
 - `Upgrade Symfony from 5.x to 6.0 <https://github.com/symfony/symfony/blob/6.4/UPGRADE-6.0.md>`_
 
-You can find more upgrade guides in the `Symfony Repository <https://github.com/symfony/symfony/tree/6.4>`_ on GitHub.
+Additional guides are available in the `Symfony GitHub repository <https://github.com/symfony/symfony/tree/6.4>`_.
+
+Twig
+----
+phpBB 4.0 uses Twig 3.14, which introduces deprecations that may impact extension and style development.
+We recommend reviewing the official Twig deprecation guide when updating your custom templates or Twig-related code:
+
+- `Twig 3.x Deprecated Features <https://twig.symfony.com/doc/3.x/deprecated.html>`_
 
 Major changes
 =============
 
 Ban system
 ----------
-The ban system has been greatly refactored for phpBB 4.0. As part of this, the following changes were introduced:
+The ban system has been significantly refactored in phpBB 4.0. Key changes include:
 
-- Added support for banning `CIDR blocks <https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing#CIDR_blocks>`_
-- Added support for IPv6 banning
-- Removed "exclude" functionality which resulted in ambiguous settings
+- `CIDR block <https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing#CIDR_blocks>`_ support for banning IP ranges.
+- IPv6 banning is now supported.
+- “Exclude” functionality has been removed due to ambiguity and inconsistent behavior.
 
 Removal of Jabber/XMPP
 ----------------------
-The Jabber/XMPP functionality has been removed from phpBB 4.0. This includes the Jabber/XMPP settings in the ACP and the Jabber/XMPP notification system.
-Users with Jabber/XMPP accounts will no longer receive notifications via Jabber/XMPP and have instead been migrated to email notifications.
-The Jabber/XMPP functionality was removed due to the lack of support for the XMPP protocol in modern browsers and the fact that it was not widely used by phpBB users.
+All Jabber/XMPP features have been removed in phpBB 4.0:
+
+- Jabber/XMPP settings in the ACP are gone.
+- XMPP-based notifications have been discontinued.
+- Users who previously used Jabber/XMPP will now receive notifications via email.
+
+This removal was driven by lack of browser support for XMPP and limited adoption within the phpBB community.
 
 Class and function changes
 ==========================
+Several classes and functions have been changed or removed. If your extension or code uses phpBB internals, you’ll want to:
+
+- Review the updated `phpBB 4.0 API documentation <https://area51.phpbb.com/docs/code/master/>`_
+- Audit your code for usages of deprecated or removed methods/classes
+
 The following table lists class and function changes that might affect custom PHP or Extension code.
-Also have a look at the `phpBB API documentation <https://area51.phpbb.com/docs/code/master/>`_ for further insight into the class and function API in phpBB 4.0.
 
 .. list-table::
    :widths: 15 15 10 10 50
@@ -145,6 +160,12 @@ Also have a look at the `phpBB API documentation <https://area51.phpbb.com/docs/
      - ``4.0.0-a1``
      - Use ``\bantu\IniGetWrapper\IniGetWrapper`` instead.
 
+   * - ``\phpbb\event\dispatcher::dispatch()``
+     - ``phpbb/event/dispatcher.php``
+     - Refactored
+     - ``4.0.0-a1``
+     - Use ``\phpbb\event\dispatcher::trigger_event()`` instead.
+
    * - ``bbcode_second_pass_by_extension``
      - ``includes/bbcode.php``
      - Removed in ``4.0.0-a1``, deprecated in ``3.2.10``
@@ -281,7 +302,7 @@ Also have a look at the `phpBB API documentation <https://area51.phpbb.com/docs/
      - ``includes/functions_compatibility.php``
      - Removed
      - ``4.0.0-a1``
-     - Use ``phpbb_delete_user_pms`` instead. Pay attention to pay array instead of single user id.
+     - Use ``phpbb_delete_users_pms()`` instead. Expects an array of users ids instead of single user id.
 
    * - ``phpbb_to_numeric``
      - ``includes/functions_compatibility.php``
@@ -389,13 +410,19 @@ Also have a look at the `phpBB API documentation <https://area51.phpbb.com/docs/
      - ``includes/functions_acp.php``
      - Removed
      - ``4.0.0-a1``
-     - Use phpbb_build_cfg_template() instead.
+     - Use ``phpbb_build_cfg_template()`` instead.
 
    * - ``h_radio``
      - ``includes/functions_acp.php``
      - Removed
      - ``4.0.0-a1``
-     - Use phpbb_build_radio() instead.
+     - Use ``phpbb_build_radio()`` instead.
+
+   * - ``build_select``
+     - ``includes/functions_acp.php``
+     - Refactored
+     - ``4.0.0-a1``
+     - Now ``build_select()`` returns an array of select options instead of a string of HTML.
 
    * - ``messenger``
      - ``includes/functions_messenger.php``
@@ -410,3 +437,29 @@ Also have a look at the `phpBB API documentation <https://area51.phpbb.com/docs/
 * **Type of change:** The type of change, e.g. added, changed, deprecated, or removed in this version.
 * **Version:** Version in which this change was introduced.
 * **Explanation:** The suggested approach to handle the change. This could involve using an alternative function, migrating code to a new approach, or providing additional information.
+
+Template function changes
+=========================
+The following table lists function changes that might affect custom Style or Extension code.
+
+.. list-table::
+   :widths: 15 10 10 65
+   :header-rows: 1
+
+   * - Function
+     - Type of change
+     - Version
+     - Explanation
+   * - ``Icon()``
+     - Added
+     - ``4.0.0-a1``
+     - Icons may be rendered using ``{{ Icon('font', 'bold') }}`` in Twig instead of manually writing HTML like ``<i class="fa-bold icon"></i>``.
+
+       Arguments:
+
+       - Icon type ('font' | 'png' | 'svg')
+       - Icon name (e.g.: 'bold')
+       - Icon title; optional, default: empty ``''``
+       - Hide the icon title from view; optional, default: ``false``
+       - Additional classes (e.g.: 'fa-fw'); optional, default: ``'fas'``
+       - Additional attributes for the icon, where the key is the attribute, ``{'data-ajax': 'mark_forums'}`` results in ``data-ajax="mark_forums"``; optional, default: ``{}``