VIP-$VIP_Number: $VIP_Title

  • Status: “one of [‘Under Discussion’, ‘Accepted’, ‘Implemented’, ‘Rejected’]”
  • Author(s): (Names)
  • Pull Request: (Link to the main pull request to resolve this VIP)
  • Release: (Which release include this VIP)

Please make a copy of this page - DO NOT EDIT this design document directly, unless you are making changes to the template.

Remove the instructions (in italics) before publishing.

Introduction (200 words at most)

This section should provide a concise and comprehensive overview of this document. After reading the introduction, the reader should have a high level understanding of the problem being solved (the “what”), why the problem is important (the “why”), and how this design intends to solve it (the “how”). When the draft design document is circulated, readers may use the introduction to determine if it is applicable to their area of work and if they are interested in reading further.

Problem Statement

This section should frame the problem clearly and state the non-negotiable requirements for a solution. There is some overlap with the Introduction section but it is here for emphasis since it forms the basis for evaluating any proposed design. There should be no disagreement on the problem statement, otherwise a design or implementation is unlikely to be successful.

Scope

Call out explicitly:

  1. What is in scope?

    For example, this functionality will only apply to batch-only stores.

  2. What is out of scope?

    For example, this functionality won’t apply to DaVinci Clients.

Project Justification

This section should justify the necessity to address the problem mentioned above, in another way, we could think about what will happen if we don’t solve the problem, and we could consider the following dimensions.

  1. New use cases.
  2. Customer experience
  3. Productivity improvement.
  4. Resilience.
  5. Operability improvement.
  6. Performance improvement.
  7. Maintainability improvement.
  8. Scalability improvement.
  9. Cost to Serve reduction.
  10. Reduce Toil.
  11. Craftsmanship improvement.
  12. Security improvement.
  13. Etc.

Functional specification

If this is a development of a functionality/product for users, specify what it should look like from the user’s point of view. It may include:

  1. Public API.
  2. Expected public behavior.
  3. Public behavior of error handling, etc.

Proposed Design

This section must describe the proposed design and implementation in detail, and how it addresses the problems outlined in the problem statement. It must provide details on alternative solutions that were considered, stating clearly why they lost out to the final design. This latter point is particularly important or else we tend to vacillate on old decisions because we cannot remember the original rationale. Phrase this section in terms of trade offs since it is rare that one approach is better in all ways; there is generally a tradeoff and making that explicit makes it much easier to understand.

The following aspects of the design must be covered when applicable:

  1. Changes to APIs or protocols or data format highlighting any compatibility issues and how they will be addressed.
  2. Major components and sequence diagrams between them.
  3. Multi-region implications including Parent/Child Controller communication.
  4. Alternative designs considered, and brief explanation of tradeoffs and decision versus the chosen design, and important aspects to consider:
    1. Security.
    2. Performance.
    3. Maintainability.
    4. Operability.
    5. Scalability.
    6. Compatibility.
    7. Testability.
    8. Risks/Mitigations.
    9. Overall effort.
    10. Leverageable.
    11. Align with the long-term vision.
  5. Preferred option by the designer/author.
    1. Conclusions/Decisions made in the design review sessions. Explanation why it’s selected

Development Milestones

This section described milestones for rather large projects so that we can set up intermediate goals for better progress management. For small projects, this may not be necessary.

Test Plan

Describe in few sentences how the functionality will be tested. How will we know that the implementation works as expected? How will we know nothing broke?

  1. What unit tests would be added to cover the critical logic?
  2. What integration tests would be added to cover major components, if they cannot be tested by unit tests?
  3. Any tests to cover performance or Security concerns.

References

List any references here.

Appendix

Add supporting information here, such as the results of performance studies and back-of-the-envelope calculations. Organize it however you want but make sure it is comprehensible to your readers.