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