mirror of
https://github.com/bigchaindb/bigchaindb.git
synced 2024-10-13 13:34:05 +00:00
197 lines
5.4 KiB
Markdown
197 lines
5.4 KiB
Markdown
# 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.
|
|
|