From 8f39950a0ee66116a803fc5b2b2d4d194b0c10be Mon Sep 17 00:00:00 2001
From: Akihiro Motoki <amotoki@gmail.com>
Date: Thu, 27 Dec 2018 03:36:55 +0900
Subject: [PATCH] Document horizon policies

This commit tries to capture basic policies on back-end feature
supports and so on that have not documented so far.

Change-Id: Ic1dc6029ce2a1cf54d313e8320b7ca206f5dfaea
---
 doc/source/contributor/index.rst           |  1 +
 doc/source/contributor/policy.rst          | 40 ++++++++++++++++++++++
 doc/source/install/system-requirements.rst |  6 +---
 3 files changed, 42 insertions(+), 5 deletions(-)
 create mode 100644 doc/source/contributor/policy.rst

diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst
index 3c7051e103..45360ae1e7 100644
--- a/doc/source/contributor/index.rst
+++ b/doc/source/contributor/index.rst
@@ -7,6 +7,7 @@
    :maxdepth: 2
 
    intro
+   policy
    quickstart
    contributing
    testing
diff --git a/doc/source/contributor/policy.rst b/doc/source/contributor/policy.rst
new file mode 100644
index 0000000000..6863d98d39
--- /dev/null
+++ b/doc/source/contributor/policy.rst
@@ -0,0 +1,40 @@
+================
+Project policies
+================
+
+This page collects basic policies on horizon development.
+
+Back-end service support
+------------------------
+
+* ``N`` release of horizon supports ``N`` and ``N-1`` releases of
+  back-end OpenStack services (like nova, cinder, neutron and so on).
+  This allows operators to upgrade horizon separately from other OpenStack
+  services.
+
+* Horizon should check features in back-end services through APIs as much as
+  possible by using micro-versioning for nova, cinder and so on and API
+  extensions for neutron (and others if any).
+
+* Related to the previous item, features available in ``N-3`` releases
+  (which means the recent four releases including the development version)
+  are assumed without checking the availability of features
+  to simplify the implementation.
+
+* Removals and deprecations of back-end feature supports basically follows
+  `the standard deprecation policy
+  <https://governance.openstack.org/tc/reference/tags/assert_follows-standard-deprecation.html>`__
+  defined by the technical committee, but there are some notes.
+  Deprecations in back-end services are applied to corresponding horizon
+  features automatically and it is allowed to drop some feature from horizon
+  without an explicit deprecation.
+
+Django support
+--------------
+
+* Horizon usually syncs with
+  `Django's Roadmap <https://www.djangoproject.com/weblog/2015/jun/25/roadmap/>`__
+  and supports LTS (long term support) versions of Django
+  as of the feature freeze of each OpenStack release.
+  Supports for other maintained Django versions are optional
+  and best-effort.
diff --git a/doc/source/install/system-requirements.rst b/doc/source/install/system-requirements.rst
index c7bde1589a..31afff1a11 100644
--- a/doc/source/install/system-requirements.rst
+++ b/doc/source/install/system-requirements.rst
@@ -13,11 +13,7 @@ The Stein release of horizon has the following dependencies.
 * Django 1.11 or 2.0
 
   * Django 1.8 to 1.10 are no longer supported since Rocky release.
-  * Horizon usually syncs with
-    `Django's Roadmap <https://www.djangoproject.com/weblog/2015/jun/25/roadmap/>`__
-    and supports LTS (long term support) versions of Django
-    as of the feature freeze of each OpenStack release.
-    Supports for other maintained Django versions are optional and best-effort.
+  * Django support policy is documented at :doc:`/contributor/policy`.
 
 * An accessible `keystone <https://docs.openstack.org/keystone/latest/>`_ endpoint