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/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