chore(docs): move deprecated platforms information around

We used to have a dedicated page for deprecated platforms information.
This document contained 2 pieces of information:

 a) the process for deprecating a platform port;
 b) the list of deprecated platforms to this day.

I think it makes more sense to move b) to the platforms ports landing
page, such that it is more visible.

This also has the nice effect to move the 'Deprecated platforms' title
as the last entry of the 'Platform ports' table of contents, like so:

 - Platform ports
   - 1. Allwinner ARMv8 SoCs
   - 2. Arm Development Platforms
     ...
   - 39. Broadcom Stingray
   - Deprecated platforms

instead of it being lost in the middle of supported platform ports.

Regarding a), this gets moved under the "Processes & Policies" section.
More specifically, it gets clubbed with the existing platform
compatibility policy. The combined document gets renamed into a
"Platforms Ports Policy" document.

Change-Id: I6e9ce2abc68b8a8ac88e7bd5f21749c14c9a2af6
Signed-off-by: Sandrine Bailleux <sandrine.bailleux@arm.com>

diff --git a/docs/about/release-information.rst b/docs/about/release-information.rst
index e9eaa80ebc7a4a1d55f82428aaaf49119ca68c50..c0875b62d314a854c880905b39c2d1bbfa777b68 100644 (file)
--- a/docs/about/release-information.rst
+++ b/docs/about/release-information.rst
@@ -56,9 +56,9 @@ depending on project requirement and partner feedback.
 Removal of Deprecated Interfaces
 --------------------------------
 
-As mentioned in the :ref:`Platform Compatibility Policy`, this is a live
-document cataloging all the deprecated interfaces in TF-A project and the
-Release version after which it will be removed.
+As mentioned in the :ref:`Platform Ports Policy`, this is a live document
+cataloging all the deprecated interfaces in TF-A project and the Release version
+after which it will be removed.
 
 +--------------------------------+-------------+---------+---------------------------------------------------------+
 | Interface                      | Deprecation | Removed | Comments                                                |
@@ -70,4 +70,4 @@ Release version after which it will be removed.
 
 --------------
 
-*Copyright (c) 2018-2021, Arm Limited and Contributors. All rights reserved.*
+*Copyright (c) 2018-2022, Arm Limited and Contributors. All rights reserved.*

diff --git a/docs/getting_started/porting-guide.rst b/docs/getting_started/porting-guide.rst
index 6996c17dbacf18992d10d19fdf7ba58b04de7946..f5a15d0aa9eaee8c33932456e3e3740883d0476a 100644 (file)
--- a/docs/getting_started/porting-guide.rst
+++ b/docs/getting_started/porting-guide.rst
@@ -23,8 +23,8 @@ Some modifications are common to all Boot Loader (BL) stages. Section 2
 discusses these in detail. The subsequent sections discuss the remaining
 modifications for each BL stage in detail.
 
-Please refer to the :ref:`Platform Compatibility Policy` for the policy
-regarding compatibility and deprecation of these porting interfaces.
+Please refer to the :ref:`Platform Ports Policy` for the policy regarding
+compatibility and deprecation of these porting interfaces.
 
 Only Arm development platforms (such as FVP and Juno) may use the
 functions/definitions in ``include/plat/arm/common/`` and the corresponding

diff --git a/docs/plat/deprecated.rst b/docs/plat/deprecated.rst
deleted file mode 100644 (file)
index 557454c..0000000
--- a/docs/plat/deprecated.rst
+++ /dev/null
@@ -1,24 +0,0 @@
-Deprecated platforms
-====================
-
-Process of deprecating a platform
----------------------------------
-
-Platform can be deprecated and its source can be kept in repository for a cooling
-off period before deleting it or it can be deleted straight away. For later types
-Deprecated/Deleted version would be same.
-
-List of deprecated platforms
-----------------------------
-
-+----------------+----------------+--------------------+--------------------+
-|    Platform    |     Vendor     | Deprecated version |  Deleted version   |
-+================+================+====================+====================+
-|    sgm775      |      Arm       |        2.5         |       2.7          |
-+----------------+----------------+--------------------+--------------------+
-|    mt6795      |      MTK       |        2.5         |       2.7          |
-+----------------+----------------+--------------------+--------------------+
-|    sgi575      |      Arm       |        2.8         |       3.0          |
-+----------------+----------------+--------------------+--------------------+
-|    rdn1edge    |      Arm       |        2.8         |       3.0          |
-+----------------+----------------+--------------------+--------------------+

diff --git a/docs/plat/index.rst b/docs/plat/index.rst
index 25d87715250b05ae10b1a3b63b53f76bef16fe85..f1b97f86a1c685e4087fbc4b2aeb9745ed1400f1 100644 (file)
--- a/docs/plat/index.rst
+++ b/docs/plat/index.rst
@@ -9,7 +9,6 @@ Platform Ports
 
    allwinner
    arm/index
-   deprecated
    meson-axg
    meson-gxbb
    meson-gxl
@@ -62,6 +61,21 @@ documentation associated with them.
    - Arm SGI-575
    - MediaTek MT8173 SoCs
 
+Deprecated platforms
+--------------------
+
++----------------+----------------+--------------------+--------------------+
+|    Platform    |     Vendor     | Deprecated version |  Deleted version   |
++================+================+====================+====================+
+|    sgm775      |      Arm       |        2.5         |       2.7          |
++----------------+----------------+--------------------+--------------------+
+|    mt6795      |      MTK       |        2.5         |       2.7          |
++----------------+----------------+--------------------+--------------------+
+|    sgi575      |      Arm       |        2.8         |       3.0          |
++----------------+----------------+--------------------+--------------------+
+|    rdn1edge    |      Arm       |        2.8         |       3.0          |
++----------------+----------------+--------------------+--------------------+
+
 --------------
 
 *Copyright (c) 2019-2022, Arm Limited. All rights reserved.*

diff --git a/docs/process/index.rst b/docs/process/index.rst
index bba2b40eb78210c10c493fca26acaca7c221a902..422ab28699d1fc2354060b4f424de0cdaafe977c 100644 (file)
--- a/docs/process/index.rst
+++ b/docs/process/index.rst
@@ -7,7 +7,7 @@ Processes & Policies
    :numbered:
 
    security
-   platform-compatibility-policy
+   platform-ports-policy
    commit-style
    coding-style
    coding-guidelines

diff --git a/docs/process/platform-compatibility-policy.rst b/docs/process/platform-compatibility-policy.rst
deleted file mode 100644 (file)
index a10236c..0000000
--- a/docs/process/platform-compatibility-policy.rst
+++ /dev/null
@@ -1,36 +0,0 @@
-Platform Compatibility Policy
-=============================
-
-Introduction
-------------
-
-This document clarifies the project's policy around compatibility for upstream
-platforms.
-
-Platform compatibility policy
------------------------------
-
-Platform compatibility is mainly affected by changes to Platform APIs (as
-documented in the :ref:`Porting Guide`), driver APIs (like the GICv3 drivers) or
-library interfaces (like xlat_table library). The project will try to maintain
-compatibility for upstream platforms. Due to evolving requirements and
-enhancements, there might be changes affecting platform compatibility which
-means the previous interface needs to be deprecated and a new interface
-introduced to replace it. In case the migration to the new interface is trivial,
-the contributor of the change is expected to make good effort to migrate the
-upstream platforms to the new interface.
-
-The deprecated interfaces are listed inside :ref:`Release Processes` as well as
-the release after which each one will be removed. When an interface is
-deprecated, the page must be updated to indicate the release after which the
-interface will be removed. This must be at least 1 full release cycle in future.
-For non-trivial interface changes, an email should be sent out to the `TF-A
-public mailing list`_ to notify platforms that they should migrate away from the
-deprecated interfaces. Platforms are expected to migrate before the removal of
-the deprecated interface.
-
---------------
-
-*Copyright (c) 2018-2022, Arm Limited and Contributors. All rights reserved.*
-
-.. _TF-A public mailing list: https://lists.trustedfirmware.org/mailman3/lists/tf-a.lists.trustedfirmware.org/

diff --git a/docs/process/platform-ports-policy.rst b/docs/process/platform-ports-policy.rst
new file mode 100644 (file)
index 0000000..7983749
--- /dev/null
+++ b/docs/process/platform-ports-policy.rst
@@ -0,0 +1,51 @@
+Platform Ports Policy
+=====================
+
+This document clarifies a couple of policy points around platform ports
+management.
+
+Platform compatibility policy
+-----------------------------
+
+Platform compatibility is mainly affected by changes to Platform APIs (as
+documented in the :ref:`Porting Guide`), driver APIs (like the GICv3 drivers) or
+library interfaces (like xlat_table library). The project will try to maintain
+compatibility for upstream platforms. Due to evolving requirements and
+enhancements, there might be changes affecting platform compatibility which
+means the previous interface needs to be deprecated and a new interface
+introduced to replace it. In case the migration to the new interface is trivial,
+the contributor of the change is expected to make good effort to migrate the
+upstream platforms to the new interface.
+
+The deprecated interfaces are listed inside :ref:`Release Processes` as well as
+the release after which each one will be removed. When an interface is
+deprecated, the page must be updated to indicate the release after which the
+interface will be removed. This must be at least 1 full release cycle in future.
+For non-trivial interface changes, an email should be sent out to the `TF-A
+public mailing list`_ to notify platforms that they should migrate away from the
+deprecated interfaces. Platforms are expected to migrate before the removal of
+the deprecated interface.
+
+Platform deprecation policy
+---------------------------
+
+If a platform is no longer maintained, it is best to deprecate it to keep the
+projects' source tree clean and healthy. Deprecation can be a 1-stage or 2-stage
+process (up to the platform maintainers).
+
+ - *2-stage*: The platform's source code can be kept in the repository for a
+   cooling off period before deleting it (typically 2 release cycles). In this
+   case, we keep track ot the *Deprecated* version separately from the *Deleted*
+   version.
+
+ - *1-stage*: The platform's source code can be deleted straight away. In this
+   case, both versions are the same.
+
+The :ref:`Platform Ports` page provides a list of all deprecated/deleted
+platform ports (or soon to be) to this day.
+
+--------------
+
+*Copyright (c) 2018-2022, Arm Limited and Contributors. All rights reserved.*
+
+.. _TF-A public mailing list: https://lists.trustedfirmware.org/mailman3/lists/tf-a.lists.trustedfirmware.org/