Merge "Design principles README section"
diff --git a/.mailmap b/.mailmap
index 516ae6f..47612b3 100644
--- a/.mailmap
+++ b/.mailmap
@@ -1,3 +1,5 @@
# Format is:
# <preferred e-mail> <other e-mail 1>
# <preferred e-mail> <other e-mail 2>
+Felipe Monteiro <felipe.carneiro.monteiro@gmail.com> <fm577c@att.com>
+Felipe Monteiro <felipe.carneiro.monteiro@gmail.com> <felipe.monteiro@att.com>
diff --git a/README.rst b/README.rst
index 6110dda..f4ab65c 100644
--- a/README.rst
+++ b/README.rst
@@ -16,6 +16,35 @@
Patrole currently offers testing for the following OpenStack services: Nova,
Neutron, Glance, Cinder and Keystone.
+Patrole is currently undergoing heavy development. As more projects move
+toward policy in code, Patrole will align its testing with the appropriate
+documentation.
+
+Design Principles
+-----------------
+
+Patrole borrows some design principles from Tempest, but not all, as its
+testing scope is confined to policies.
+
+* *Stability*. Patrole uses OpenStack public interfaces. Tests in Patrole
+ should only touch public OpenStack APIs.
+* *Atomicity*. Patrole tests should be atomic: they should test policies in
+ isolation. Unlike Tempest, a Patrole test strives to only call a single
+ endpoint at a time.
+* *Holistic coverage*. Patrole strives for complete coverage of the OpenStack
+ API. Additionally, Patrole strives to test the API-to-policy mapping
+ contained in each project's policy in code documentation.
+* *Self-contained*. Patrole should attempt to clean up after itself; whenever
+ possible we should tear down resources when done.
+
+ .. note::
+
+ Patrole modifies roles dynamically in the background, which affects
+ pre-provisioned credentials. Work is currently underway to clean up
+ modifications made to pre-provisioned credentials.
+
+* *Self-tested*. Patrole should be self-tested.
+
Features
--------
* Validation of default policy definitions located in policy.json files.