Merge pull request #1877 from bigchaindb/template-spec

Add guidelines for new features in BigchainDB

.github/issue_template.md

@@ -1,3 +1,9 @@
+**Please use the template below for bug reports or minor feature requests.** 
+
+**For relatively bigger/significant feature requests please refer to our guidelines about**
+**[feature contribution](https://github.com/bigchaindb/bigchaindb/blob/master/proposals/README.md)**
+**and remove the existing template.**
+
 * BigchainDB version:
 * Operating System:
 * Deployment Type: `[Docker|Host|IPDB|Other]`
@@ -23,4 +29,4 @@ ocassionally, please provide additional information; e.g. screenshots, commands,
 ```
 Paste the command(s) you ran and the output.
 If there was a crash, please include the traceback/error message here.
-```
+```

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](./proposals/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
 
@@ -138,7 +141,7 @@ git push origin new-branch-name
 
 ### 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).
 

proposals/README.md

@@ -0,0 +1,61 @@
+# 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 `dev 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
+
+## 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
+Submit a design specification document (Pull Request) of your feature. The spec needs to be submitted at:
+
+```text
+/path/to/repo/bigchaindb/proposals
+``` 
+
+The PR for the specification document should be
+[linked](https://help.github.com/articles/autolinked-references-and-urls/) to the GitHub issue you created and
+marked with `Spec` label.
+
+**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.md)
+
+## Almost there
+Once, you have submitted the design specification document:
+
+- Get it reviewed.
+- Discuss.
+- Address comments(if any).
+- Get it merged.
+
+Once, your specification document is merged, it will be tracked for an upcoming release.

proposals/examples/example-feature-x-spec.md

@@ -0,0 +1,196 @@
+# 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.
+
+```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**
+
+```json
+
+      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.
+