Add guidelines for new features in BigchainDB

- Template specification document
- Update CONTRIBUTING.md to reflect changes

.github/issue_template.md

@@ -1,3 +1,5 @@
+**For new feature(s) or feature request(s) please refer to our guidelines about [contribution](https://github.com/bigchaindb/bigchaindb/blob/master/CONTRIBUTING.md)**
+
 * BigchainDB version:
 * Operating System:
 * Deployment Type: `[Docker|Host|IPDB|Other]`

CONTRIBUTING.md

@@ -22,7 +22,10 @@ To prevent that situation, we ask that all pull requests should resolve, address
 
 When you submit a pull request, please mention the issue (or issues) that it resolves, e.g. "Resolves #123".
 
-Exception: hotfixes and minor changes don't require a pre-existing issue, but please write a thorough pull request description.
+**Note:** For feature request(s) or new feature(s), please consult our [feature contribution guidelines](./docs/specs/README.md).
+
+**Exception(s):**
+- Hotfixes and minor changes don't require a pre-existing issue, but please write a thorough pull request description.
 
 ### Step 1 - Prepare and Familiarize Yourself
 
@@ -133,9 +136,9 @@ Make sure you've commited all the additions or changes you want to include in yo
 git push origin new-branch-name
 ```
 
-### Step 10 - Create a Pull Request 
+### Step 10 - Create a Pull Request
 
-Go to the GitHub website and to _your_ remote bigchaindb repository (i.e. something like https://github.com/your-user-name/bigchaindb). 
+Go to the GitHub website and to _your_ remote bigchaindb repository (i.e. something like https://github.com/your-user-name/bigchaindb).
 
 See [GitHub's documentation on how to initiate and send a pull request](https://help.github.com/articles/using-pull-requests/). Note that the destination repository should be `bigchaindb/bigchaindb` and the destination branch will be `master` (usually, and if it's not, then we can change that if necessary).
 

docs/specs/README.md

@@ -0,0 +1,66 @@
+# Guidelines for Feature Request(s)
+
+This document covers, how to contribute new feature(s) or significant design changes to BigchainDB. Since, contribution
+of such functionality involves design discussion and might take multiple releases to complete,
+we expect the contributors to follow certain guidelines before proceeding with the implementation.
+
+
+## Classification
+How to classify your contribution as a feature and determine if it needs design discussion. 
+
+Here are some baseline criterion that can help you classify your idea, as a feature:
+
+- Requires significant effort/changes to the current BigchainDB implementation and it is not self
+ contained (e.g. API changes,  introducing a new component, takes more than 20 Wrigleys
+ (Wrigley is a `man day` @ BigchainDB))
+- Impacts the clients and drivers.
+- Can we write a blog post about it?
+- Requires collaboration with multiple teams in terms of development, operations and testing.
+- Impacts documentation significantly.
+
+It is not a feature if:
+
+- It is straightforward enough and might not need a design discussion.
+  - Test case fixes
+  - Fixing typos/grammar in documentation.
+  - Refactoring code
+  - Adding error or log messages.
+
+## Classified as a Feature?
+Create a new issue on our [GitHub repository](https://github.com/bigchaindb/bigchaindb/issues/new) with a
+`Feature-Request` label, once you have classified your proposal as a feature and:
+
+- Scratched the surface.
+  - Discussed the proposal in the community e.g. on [our Gitter channel](https://gitter.im/bigchaindb/bigchaindb),
+  Or [Twitter](https://twitter.com/BigchainDB) and saw interest.
+- *Optional:* Have a working prototype.
+- Worked out the resources and people, who can contribute towards this feature.
+
+## Submit Spec
+After creating an issue with an appropriate problem statement and details, submit a design specification document
+of your feature. The spec needs to be submitted at:
+
+```bash
+$ /path/to/repo/bigchaindb/docs/specs/features/release-<latest-release>
+``` 
+
+The PR for the specification document should be
+[linked](https://help.github.com/articles/autolinked-references-and-urls/) to the GitHub issue with you created and
+you also need to update the `spec-index.rst` inside the `/path/to/release-<latest-release>` directory, and mention
+your spec under `Tracked specs`.
+
+**Note:** Feature(s) cannot be backported. Hence, only commit your proposal to the latest release.
+
+[How do I write a design specification document?](examples/example-feature-x-spec.rst)
+
+## Almost there
+Once, you have submitted the design specification document:
+
+- Get it reviewed.
+- Discuss.
+- Address comments(if any).
+- Get it merged.
+- Start implementing.
+
+Once your spec is merged, you can start with the implementation. Voila!
+

docs/specs/examples/example-feature-x-spec.rst

@@ -0,0 +1,216 @@
+Example
+=======
+
+Feature X: Design specification document
+----------------------------------------
+
+Introduction paragraph - A simple explanation of what are we trying to accomplish with this feature.
+Should be simple enough that even novice users/developers can understand. Ideally, this paragraph
+should be made part of the feature PR(Pull Request).
+
+  * If you want to provide a diagram with your specification document, please use
+    ascii diagrams (plain text).
+    
+    * `asciiflow <http://asciiflow.com/>`_ is a good tool to get started.
+
+  * **TODO:** We will add more guidelines on the formatting later.
+
+.. note::
+
+    If any of the sections mentioned in this example is not applicable to your feature.
+    Please add **None** under that section, instead of removing the heading/section.
+
+Problem Description
+-------------------
+
+A detailed description of the problem that we are trying to solve.
+
+Use Cases
+^^^^^^^^^
+
+What use cases does this feature address? Impact on actors i.e. Developer, Consumer/User, Deployer etc.
+
+Proposed Change
+---------------
+
+A detailed description of how you are proposing to solve the problem statement and the scope of this effort.
+
+* You can also include the architecture diagram in this section.
+
+    .. code:: text
+
+        Sample architecture diagram
+
+        +------------+                 +----------------------+
+        |            |                 | +-----------+        |
+        |            |                 | |Feature|X  |        |
+        |            |                 | +-----------+        |
+        |            |                 |                      |
+        |            |                 |                      |
+        |            |                 |                      |
+        +------------+                 +----------------------+
+
+        Old Architecture               New Architecture
+
+  
+
+
+Alternatives
+^^^^^^^^^^^^
+
+  * Are there any other ways in which you can address this problem statement? 
+  * What are they?
+  * Why aren't we using them?
+
+Try to keep this short and precise, no need for a deep comparative analysis.
+
+Data model impact
+^^^^^^^^^^^^^^^^^
+
+Will the feature modify the data model? If yes, how? Please cover all the details regarding the impact.
+
+  * New data objects that will be introduced?
+  * Existing database schema changes?
+  * Database migrations? i.e. if there are existing deployments/instances, how will be modify/update
+    them?
+
+API impact
+^^^^^^^^^^
+
+Details about the impacted APIs and covering each API method.
+
+Following details about each method should be covered:
+  * Method Type(PUT/POST/GET/DELETE)
+  * Expected response code(s)
+  * Expected error response code(s)
+  * URL
+  * Parameters which can be passed via url.
+  * Schema definition for body (JSON and if body data is allowed).
+  * Schema definition for response (if any).
+  * Accessibility of API(Does it introduce any policy? or policy changes?)
+  * Example
+
+Sample request/reponses:
+
+Create Request:
+
+    .. code:: text
+
+      POST /api/v1/newfeature/
+      {
+        "newfeature": {
+            "key-1": "value",
+            "key-2": "value",
+          }
+      }
+
+      Response:
+      {
+        "newfeature": {
+            "key-1": "value",
+            "key-2": "value",
+            "key-2": "value",
+        }
+      }
+
+
+Security impact
+^^^^^^^^^^^^^^^
+
+Does the feature have an impact on the existing system?
+
+  * Does this feature touch sensitive information e.g. keys, user data?
+  * Does this feature, introduce or alter an API in a way that sensitive information can be accessed?
+  * Does this change required use of sudo? or root priviliges?
+  * Crypto changes?
+
+
+Performance impact
+^^^^^^^^^^^^^^^^^^
+
+Does this feature have an impact on the performance of the existing system?
+
+Things to consider:
+
+  * Changes in a commonly used utility function or decorator? Can cause performance degradation.
+  * Database queries. 
+  * Locking? Concurrency? Change in the existing behavior?
+
+End user impact
+^^^^^^^^^^^^^^^
+
+Besides the API, does this change impact any of the drivers? How?
+
+Deployment impact
+^^^^^^^^^^^^^^^^^
+
+Does this feature affect how we deploy BigchainDB/IPDB clusters? 
+
+Things to consider:
+
+  * Configuration changes?
+  * New components introduced by the feature?
+  * How to deploy?(working samples/documentation)
+  * Will this impact CI, once this is merged? 
+
+Documentation impact
+^^^^^^^^^^^^^^^^^^^^
+
+What is the impact of this feature on documentation? 
+
+Testing impact
+^^^^^^^^^^^^^^
+
+Please, discuss the impact on existing testing framework and how this feature should be tested.
+
+Things to consider:
+
+  * Will this feature change existing behavior of tests?
+  * Any specific scenarios that need to be tested?
+  * Any limitations in the current test infrastructure to test this feature?
+
+Implementation
+--------------
+
+Assignee(s)
+^^^^^^^^^^^
+Resource(s) working on this feature and there roles e.g.
+
+Primary assignee(s):
+  <github-profile OR Name>
+
+Other contributor(s):
+  <github-profile OR Name>
+
+Action Items
+^^^^^^^^^^^^
+
+Action items or tasks - breaking the feature into sprints or smaller tickets if possible.
+Add links to tickets if possible. Update the design specification if something pops up later
+in the development cycle.
+
+Targeted Release
+^^^^^^^^^^^^^^^^
+
+Targeted release version, if known. 
+
+e.g. **3.0**
+
+Dependencies
+------------
+
+  * If any project(s)/effort(s) depend on this change or related to.
+  * If this feature depends on functionality from another change/feature.
+  * Any library dependencies? Or versioning?
+
+Reference(s)
+------------
+
+Please add useful reference(s) here.
+
+  * URL of the GitHub issue containing the proposal/feature request.
+  * Links to reference material.
+  * Links to tickets/discussions.
+  * Related specifications.
+  * Anything that you feel is useful.
+

docs/specs/features/release-1.3/spec-index.rst

@@ -0,0 +1,12 @@
+BigchainDB Design Specs
+=======================
+
+List of approved design specification documents. 
+
+    .. note::
+
+        We can move the design specification document(s)/discussion(s) to another repository
+        if need be.
+
+Tracked specs
+-------------