Docs: Add documentation on policy feature flags
This is to add documentation on policy feature flags, recently
introduced in [0].
[0] Ia0d9847908a8e723446c16465d68cd7f622c04cc
Depends-On: Ia47132fa596918e58f21ba9810c2c28ddcf0d584
Change-Id: I3e630c535074e3a9ce8e9b07a1909984d70cef12
diff --git a/HACKING.rst b/HACKING.rst
index 056c86a..f020063 100644
--- a/HACKING.rst
+++ b/HACKING.rst
@@ -53,3 +53,67 @@
Patrole does not have a hacking check for role overriding, but one may be
added in the future.
+
+Branchless Patrole Considerations
+---------------------------------
+
+Like Tempest, Patrole is branchless. This is to better ensure API and RBAC
+consistency between releases because API and RBAC behavior should not change
+between releases. This means that the stable branches are also gated by the
+Patrole master branch, which also means that proposed commits to Patrole must
+work against both the master and all the currently supported stable branches
+of the projects. As such there are a few special considerations that have to
+be accounted for when pushing new changes to Patrole.
+
+1. New Tests for new features
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Patrole, like Tempest, *implicitly* tests new features because new policies
+oftentimes accompany new features. The same `Tempest philosophy`_ regarding
+feature flags and new features also applies to Patrole.
+
+.. _Tempest philosophy: https://docs.openstack.org/tempest/latest/HACKING.html#new-tests-for-new-features
+
+2. New Tests for new policies
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When adding tests for new policies that were not in previous releases of the
+projects, the new test must be properly skipped with a feature flag. This
+involves using the ``testtools.skip(Unless|If)`` decorator above the test
+to check if the required policy is enabled. Similarly, a feature flag must
+be used whenever an OpenStack service covered by Patrole changes one of its
+policies in a backwards-incompatible way. If there isn't a method of selecting
+the new policy from the config file then there won't be a mechanism to disable
+the test with older stable releases and the new test won't be able to merge.
+
+Introduction of a new feature flag requires specifying a default value for the
+corresponding config option that is appropriate in the latest OpenStack
+release. Because Patrole is branchless, the feature flag's default value will
+need to be overridden to a value that is appropriate in earlier releases in
+which the feature isn't available. In DevStack, this can be accomplished by
+modifying Patrole's lib installation script for previous branches (because
+DevStack is branched).
+
+3. Bug fix on core project needing Patrole changes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When trying to land a bug fix which changes a tested API you'll have to use the
+following procedure:
+
+ #. Propose change to the project, get a +2 on the change even with the
+ test failing Patrole side.
+ #. Propose skip to the relevant Patrole test which will only be approved
+ after the corresponding change in the project has a +2.
+ #. Land project change in master and all open stable branches
+ (if required).
+ #. Land changed test in Patrole.
+
+Otherwise the bug fix won't be able to land in the project.
+
+4. New Tests for existing features or policies
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The same `Tempest logic`_ regarding new tests for existing features or
+policies also applies to Patrole.
+
+.. _Tempest logic: https://docs.openstack.org/tempest/latest/HACKING.html#new-tests-for-existing-features
diff --git a/doc/source/configuration.rst b/doc/source/configuration.rst
index f477a3e..f6aaf04 100644
--- a/doc/source/configuration.rst
+++ b/doc/source/configuration.rst
@@ -55,3 +55,46 @@
Patrole currently does not support policy files located on a host different
than the one on which it is running.
+
+Policy Feature Flags
+--------------------
+
+Patrole's ``[policy-feature-enabled]`` configuration group includes one option
+per supported policy feature flag. These feature flags are introduced when an
+OpenStack service introduces a new policy or changes a policy in a
+backwards-incompatible way. Since Patrole is branchless, it copes with the
+unexpected policy change by making the relevant policy change as well, but
+also introduces a new policy feature flag so that the test won't break N-1/N-2
+releases where N is the currently supported release.
+
+The default value for the feature flag is enabled for N and disabled for any
+releases prior to N in which the feature is not available. This is done by
+overriding the default value of the feature flag in DevStack's ``lib/patrole``
+installation script. The change is made in Tempest's DevStack script because
+Patrole's DevStack plugin is hosted in-repo, which is branch-less (whereas
+the former is branched).
+
+After the backwards-incompatible change no longer affects any supported
+release, then the corresponding policy feature flag is removed.
+
+For more information on feature flags, reference the relevant
+`Tempest documentation`_.
+
+.. _Tempest documentation: https://docs.openstack.org/tempest/latest/HACKING.html#1-new-tests-for-new-features
+
+Sample Configuration File
+-------------------------
+
+The following is a sample Patrole configuration for adaptation and use. It is
+auto-generated from Patrole when this documentation is built, so
+if you are having issues with an option, please compare your version of
+Patrole with the version of this documentation.
+
+Note that the Patrole configuration options actually live inside the Tempest
+configuration file; at runtime, Tempest populates its own configuration
+file with Patrole groups and options, assuming that Patrole is correctly
+installed and recognized as a plugin.
+
+The sample configuration can also be viewed in `file form <_static/patrole.conf.sample>`_.
+
+.. literalinclude:: _static/patrole.conf.sample
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 237c0b7..d964845 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -13,7 +13,6 @@
configuration
usage
- sampleconf
Patrole Installation Guide
--------------------------
diff --git a/doc/source/sampleconf.rst b/doc/source/sampleconf.rst
deleted file mode 100644
index ee848b5..0000000
--- a/doc/source/sampleconf.rst
+++ /dev/null
@@ -1,18 +0,0 @@
-.. _patrole-sampleconf:
-
-Sample Configuration File
-==========================
-
-The following is a sample Patrole configuration for adaptation and use. It is
-auto-generated from Patrole when this documentation is built, so
-if you are having issues with an option, please compare your version of
-Patrole with the version of this documentation.
-
-Note that the Patrole configuration options actually live inside the Tempest
-configuration file; at runtime, Tempest populates its own configuration
-file with Patrole groups and options, assuming that Patrole is correctly
-installed and recognized as a plugin.
-
-The sample configuration can also be viewed in `file form <_static/patrole.conf.sample>`_.
-
-.. literalinclude:: _static/patrole.conf.sample