...
- Link to the corresponding JIRA ticket first. Do not miss this.
- Brief description of the issue been tackled ( Summary )
- Use cases or user stories on how this feature will be used by end-users
- Design Goals should be stated clearly. Why is this feature required?
- Also iterate about specific non-goals if there are any (e.g. functionality or extension that might be added in the future, but it's not part of this proposal intentionally)
- Design assumptions/ pre-reqs ( what are the pre-requisites for this feature ) should be laid out. Clearly say what this feature will not be doing.
- If the feature is large enough, break down the design document into chunks/ phases or highlight it in the design doc
- If there are alternatives you explored before coming up with this design, write it down in section. It could be some research you did, put this down in the design wiki, even better to have Solution 1..n highlighted with Pros/Cons for each. A table comparing the different solutions would also help.
- Have a section for open questions, if you still are not sure of some of the design options you chose. It will give the reviewers a heads up to provide valuable feedback on the design
- What are the external jar dependencies if any?
- New Connector will be added? Explain the details of the dependencies
- Modifying an existing connector
- Outline the upgrade path for the connector if any?
- New APIs will be added? What are they?
- Outline the plan for documenting these new APIs
- Designing good extensible APIs is an art! Rationalize why it is a Interface, AbstractClass or Annotation ? Every attribute/ method in the API should tell a coherent story
- Will there be a custom reference implementation?
- Modifying existing APIs
- Modifying REST APIs
- Modifying Connector APIs
- Modifying Repository APIs
- Modifying Execution Engine APIs
- Modifying the Intermediate Data Format related APIs
- What form of tests will be written ?
- Outline for the Integration tests if applicable
- Will the feature change the command line client ?
- Will the feature change the java client?
- Does it include any repository changes?
- Outline the changes to the relevant repository models
- Outline of the upgrade tests that will be written for the repository changes if any ?
...