Merge pull request #1600 from soby-mathew/sm/compat_policy_doc

docs: Add platform compatibility policy document

docs/plaform-compatibility-policy.rst

+TF-A Platform Compatibility Policy
+======================================================
+
+
+.. section-numbering::
+    :suffix: .
+
+.. contents::
+
+--------------
+
+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 `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 `Release information`_ documents the deprecated interfaces and the intended
+release after which it 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, a `tf-issue`_ should be posted 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, Arm Limited and Contributors. All rights reserved.*
+
+.. _Porting Guide: ./porting-guide.rst
+.. _Release information: https://github.com/ARM-software/arm-trusted-firmware/wiki/TF-A-Release-information#2removal-of-deprecated-interfaces
+.. _tf-issue: https://github.com/ARM-software/tf-issues/issues
\ No newline at end of file

docs/porting-guide.rst

@@ -41,6 +41,9 @@ modifications for each BL stage in detail.
 
 This document should be read in conjunction with the TF-A `User Guide`_.
 
+Please refer to the `Platform compatibility policy`_ for the policy regarding
+compatibility and deprecation of these porting interfaces.
+
 Common modifications
 --------------------
 
@@ -2835,6 +2838,7 @@ amount of open resources per driver.
 .. _Firmware Design: firmware-design.rst
 .. _PSCI: http://infocenter.arm.com/help/topic/com.arm.doc.den0022c/DEN0022C_Power_State_Coordination_Interface.pdf
 .. _plat/arm/board/fvp/fvp\_pm.c: ../plat/arm/board/fvp/fvp_pm.c
+.. _Platform compatibility policy: https://github.com/ARM-software/arm-trusted-firmware/docs/platform-compatibility-policy.rst#2platform-compatibility-policy
 .. _IMF Design Guide: interrupt-framework-design.rst
 .. _Arm Generic Interrupt Controller version 2.0 (GICv2): http://infocenter.arm.com/help/topic/com.arm.doc.ihi0048b/index.html
 .. _3.0 (GICv3): http://infocenter.arm.com/help/topic/com.arm.doc.ihi0069b/index.html