1Platform Ports Policy
2=====================
3
4This document clarifies a couple of policy points around platform ports
5management.
6
7Platform compatibility policy
8-----------------------------
9
10Platform compatibility is mainly affected by changes to Platform APIs (as
11documented in the :ref:`Porting Guide`), driver APIs (like the GICv3 drivers) or
12library interfaces (like xlat_table library). The project will try to maintain
13compatibility for upstream platforms.
14
15Due to evolving requirements and enhancements, there might be changes affecting
16platform compatibility, which means the previous interface needs to be deprecated
17and a new interface introduced to replace it. In case the migration to the new
18interface is trivial, the contributor of the change is expected to make good
19effort to migrate the upstream platforms to the new interface.
20
21The project will generally not take into account downstream platforms. If those
22are affected by a deprecation / removal decision, we encourage their maintainers
23to upstream their platform code or copy the latest version of the code being
24deprecated into their downstream tree.
25
26The deprecated interfaces are listed inside :ref:`Release Processes` as well as
27the release after which each one will be removed. When an interface is
28deprecated, the page must be updated to indicate the release after which the
29interface will be removed. This must be at least 1 full release cycle in future.
30For non-trivial interface changes, an email should be sent out to the `TF-A
31public mailing list`_ to notify platforms that they should migrate away from the
32deprecated interfaces. Platforms are expected to migrate before the removal of
33the deprecated interface.
34
35Deprecation policy
36------------------
37
38If a platform, driver or library interface is no longer maintained, it is best
39to deprecate it to keep the projects' source tree clean and healthy. Deprecation
40can be a 1-stage or 2-stage process (up to the maintainers).
41
42 - *2-stage*: The source code can be kept in the repository for a cooling off
43   period before deleting it (typically 2 release cycles). In this case, we keep
44   track of the *Deprecated* version separately from the *Deleted* version.
45
46 - *1-stage*: The source code can be deleted straight away. In this case, both
47   versions are the same.
48
49The :ref:`Platform Ports` page provides a list of all deprecated/deleted
50platform ports (or soon to be) to this day.
51
52--------------
53
54*Copyright (c) 2018-2023, Arm Limited and Contributors. All rights reserved.*
55
56.. _TF-A public mailing list: https://lists.trustedfirmware.org/mailman3/lists/tf-a.lists.trustedfirmware.org/
57