Merge "Patrole base job as zuulv3 native"
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 308c12c..be3264e 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -14,6 +14,7 @@
    installation
    configuration
    usage
+   testing
    sampleconf
 
 Developer's Guide
diff --git a/doc/source/installation.rst b/doc/source/installation.rst
index c244152..b9cc924 100644
--- a/doc/source/installation.rst
+++ b/doc/source/installation.rst
@@ -10,12 +10,13 @@
 At the command line::
 
     $ git clone http://git.openstack.org/openstack/patrole
-    $ sudo pip install patrole
+    $ sudo pip install ./patrole
 
 Or, if you have virtualenvwrapper installed::
 
-    $ mkvirtualenv patrole
-    $ sudo pip install patrole
+    $ mkvirtualenv patrole_env
+    $ workon patrole_env
+    $ pip install ./patrole
 
 Or to install from the source::
 
diff --git a/doc/source/testing.rst b/doc/source/testing.rst
new file mode 100644
index 0000000..d61c78d
--- /dev/null
+++ b/doc/source/testing.rst
@@ -0,0 +1,51 @@
+.. _patrole-testing:
+
+===============
+Patrole Testing
+===============
+
+Testing Scope
+=============
+
+Patrole testing scope is strictly confined to Role-Based Access Control
+(RBAC). In OpenStack, ``oslo.policy`` is the RBAC library used by all
+major services. Thus, Patrole is concerned with validating that public API
+endpoints are correctly using ``oslo.policy`` for authorization.
+
+In other words, all tests in Patrole are RBAC tests.
+
+Stable Tests
+============
+
+In the discussion below, "correct" means that a test is consistent with
+a service's API-to-policy mapping and "stable" means that a test should
+require minimal maintenance for the supported releases.
+
+Present
+-------
+
+During the Queens release, a `governance spec`_ was pushed to support policy
+in code, which documents the mapping between APIs and each of their policies.
+
+This documentation is an important prerequisite for ensuring that Patrole
+tests for a given service are correct. This mapping can be referenced to
+confirm that Patrole's assumed mapping for a test is correct. For
+example, Nova has implemented policy in code which can be used to verify
+that Patrole's Nova RBAC tests use the same mapping.
+
+If a given service does not have policy in code, this implies that it is
+*more likely* that the RBAC tests for that service are inconsistent with the
+*intended* policy mapping. Until that service implements policy in code, it
+is difficult for Patrole maintainers to verify that tests for that service
+are correct.
+
+Future
+------
+
+Once all services that Patrole tests have implemented policy in code --
+and once Patrole has updated all its tests in accordance with the policy in
+code documentation -- then Patrole tests can guaranteed to be stable.
+
+This stability will be denoted with a 1.0 version release.
+
+.. _governance spec: https://governance.openstack.org/tc/goals/queens/policy-in-code.html
diff --git a/releasenotes/source/index.rst b/releasenotes/source/index.rst
index 8c90aae..ce29994 100644
--- a/releasenotes/source/index.rst
+++ b/releasenotes/source/index.rst
@@ -6,5 +6,6 @@
    :maxdepth: 1
 
    unreleased
+   v0.3.0
    v0.2.0
    v0.1.0
diff --git a/releasenotes/source/v0.3.0.rst b/releasenotes/source/v0.3.0.rst
new file mode 100644
index 0000000..5b6f04a
--- /dev/null
+++ b/releasenotes/source/v0.3.0.rst
@@ -0,0 +1,6 @@
+====================
+v0.3.0 Release Notes
+====================
+
+.. release-notes:: 0.3.0 Release Notes
+   :version: 0.3.0
diff --git a/requirements.txt b/requirements.txt
index 35c6038..cc13aa9 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -3,7 +3,7 @@
 # process, which may cause wedges in the gate later.
 pbr!=2.1.0,>=2.0.0 # Apache-2.0
 oslo.log>=3.36.0 # Apache-2.0
-oslo.config>=5.1.0 # Apache-2.0
+oslo.config>=5.2.0 # Apache-2.0
 oslo.policy>=1.30.0 # Apache-2.0
 tempest>=17.1.0 # Apache-2.0
 stevedore>=1.20.0 # Apache-2.0
diff --git a/test-requirements.txt b/test-requirements.txt
index add2388..475d1e5 100644
--- a/test-requirements.txt
+++ b/test-requirements.txt
@@ -3,7 +3,7 @@
 # process, which may cause wedges in the gate later.
 hacking>=1.0.0 # Apache-2.0
 
-sphinx!=1.6.6,>=1.6.2 # BSD
+sphinx!=1.6.6,!=1.6.7,>=1.6.2 # BSD
 openstackdocstheme>=1.18.1 # Apache-2.0
 reno>=2.5.0 # Apache-2.0
 fixtures>=3.0.0 # Apache-2.0/BSD