From 3bac4060f5a2f297ae270eaf0729a030fd15444d Mon Sep 17 00:00:00 2001
From: Ihar Hrachyshka <ihrachys@redhat.com>
Date: Sat, 12 Nov 2016 17:34:52 +0000
Subject: [PATCH] Document how to proceed with new platform features

Updated effective neutron guide to reflect that we should not start
using new features in code without checking common platform for these
features' availability in distro packages. If some are indeed missing a
feature, we may need to revisit the direction, or talk to distros, or
handle failures gracefully.

Change-Id: I38cbe19ae0134fb129aad1fa80cc712a17ab94ad
Related-Bug: #1644312
---
 doc/source/devref/effective_neutron.rst |  7 ++++
 doc/source/policies/code-reviews.rst    | 47 +++++++++++++++++++++++++
 2 files changed, 54 insertions(+)

diff --git a/doc/source/devref/effective_neutron.rst b/doc/source/devref/effective_neutron.rst
index 9a204a0ff55..69d6546743e 100644
--- a/doc/source/devref/effective_neutron.rst
+++ b/doc/source/devref/effective_neutron.rst
@@ -207,6 +207,13 @@ System development
 Document common pitfalls as well as good practices done when invoking system commands
 and interacting with linux utils.
 
+* When a patch requires a new platform tool or a new feature in an existing
+  tool, check if common platforms ship packages with the aforementioned
+  feature. Also, tag such a patch with ``UpgradeImpact`` to raise its
+  visibility (as these patches are brought up to the attention of the core team
+  during team meetings). More details in `review guidelines
+  <http://docs.openstack.org/developer/neutron/policies/code-reviews.html#neutron-spec-review-practices>`_.
+
 Eventlet concurrent model
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/doc/source/policies/code-reviews.rst b/doc/source/policies/code-reviews.rst
index bdc102c9e3a..2058bbd1cd6 100644
--- a/doc/source/policies/code-reviews.rst
+++ b/doc/source/policies/code-reviews.rst
@@ -12,6 +12,53 @@ Neutron follows the `code review guidelines <https://wiki.openstack.org/wiki/Rev
 set forth for all OpenStack projects. It is expected that all reviewers are following the guidelines
 set forth on that page.
 
+In addition to that, the following rules are to follow:
+
+* Any change that requires a new feature from Neutron runtime dependencies
+  requires special review scrutiny to make sure such a change does not break
+  a supported platform (examples of those platforms are latest Ubuntu LTS or
+  CentOS). Runtime dependencies include but are not limited to: kernel, daemons
+  and tools as defined in ``oslo.rootwrap`` filter files, runlevel management
+  systems, as well as other elements of Neutron execution environment.
+
+  .. note::
+
+     For some components, the list of supported platforms can be wider than
+     usual. For example, Open vSwitch agent is expected to run successfully in
+     Win32 runtime environment.
+
+  #. All such changes must be tagged with ``UpgradeImpact`` in their commit
+     messages.
+
+  #. Reviewers are then advised to make an effort to check if the newly
+     proposed runtime dependency is fulfilled on supported platforms.
+
+  #. Specifically, reviewers and authors are advised to use existing gate and
+     experimental platform specific jobs to validate those patches. To trigger
+     experimental jobs, use the usual protocol (posting ``check experimental``
+     comment in Gerrit). CI will then execute and report back a baseline of
+     Neutron tests for platforms of interest and will provide feedback on the
+     effect of the runtime change required.
+
+  #. If review identifies that the proposed change would break a supported
+     platform, advise to rework the patch so that it's no longer breaking the
+     platform. One of the common ways of achieving that is gracefully falling
+     back to alternative means on older platforms, another is hiding the new
+     code behind a conditional, potentially controlled with a ``oslo.config``
+     option.
+
+     .. note::
+
+        Neutron team retains the right to remove any platform conditionals in
+        future releases. Platform owners are expected to accommodate in due
+        course, or otherwise see their platforms broken. The team also retains
+        the right to discontinue support for unresponsive platforms.
+
+  #. The change should also include a new `sanity check
+     <https://git.openstack.org/cgit/openstack/neutron/tree/neutron/cmd/sanity/checks.py>`_
+     that would help interested parties to identify their platform limitation
+     in timely manner.
+
 Neutron Spec Review Practices
 -----------------------------
 In addition to code reviews, Neutron also maintains a BP specification git repository. Detailed