mirror of
https://github.com/bigchaindb/bigchaindb.git
synced 2024-10-13 13:34:05 +00:00
Add guidelines for new features in BigchainDB
- Template specification document - Update CONTRIBUTING.md to reflect changes
This commit is contained in:
muawiakh
parent
bc4f8fcab5
commit
27aa8555aa
2
.github/issue_template.md
vendored
2
.github/issue_template.md
vendored
@ -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]`
|
||||
|
||||
@ -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).
|
||||
|
||||
|
||||
66
docs/specs/README.md
Normal file
66
docs/specs/README.md
Normal file
@ -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!
|
||||
|
||||
216
docs/specs/examples/example-feature-x-spec.rst
Normal file
216
docs/specs/examples/example-feature-x-spec.rst
Normal file
@ -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.
|
||||
|
||||
12
docs/specs/features/release-1.3/spec-index.rst
Normal file
12
docs/specs/features/release-1.3/spec-index.rst
Normal file
@ -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
|
||||
-------------
|
||||
Loading…
x
Reference in New Issue
Block a user