diff --git a/.github/issue_template.md b/.github/issue_template.md index 1446da07..5ed53bca 100644 --- a/.github/issue_template.md +++ b/.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. -``` \ No newline at end of file +``` diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4aad9d23..687fe7d0 100644 --- a/CONTRIBUTING.md +++ b/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). diff --git a/proposals/README.md b/proposals/README.md new file mode 100644 index 00000000..e4a833e9 --- /dev/null +++ b/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. diff --git a/proposals/examples/example-feature-x-spec.md b/proposals/examples/example-feature-x-spec.md new file mode 100644 index 00000000..ecfbd847 --- /dev/null +++ b/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. +