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