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

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 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.

        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

      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.