github.com/pingcap/tiflow@v0.0.0-20240520035814-5bf52d54e205/docs/design/TEMPLATE.md (about)

     1  # TiCDC Design Documents
     2  
     3  - Author(s): [Author Name](http://github.com/your-github-id), [Co-Author Name](http://github.com/your-github-id), ...
     4  - Discussion PR: https://github.com/pingcap/tiflow/pull/XXX
     5  - Tracking Issue: https://github.com/pingcap/tiflow/issues/XXX
     6  
     7  ## Table of Contents
     8  
     9  - [Introduction](#introduction)
    10  - [Motivation or Background](#motivation-or-background)
    11  - [Detailed Design](#detailed-design)
    12  - [Test Design](#test-design)
    13    - [Functional Tests](#functional-tests)
    14    - [Scenario Tests](#scenario-tests)
    15    - [Compatibility Tests](#compatibility-tests)
    16    - [Benchmark Tests](#benchmark-tests)
    17  - [Impacts & Risks](#impacts--risks)
    18  - [Investigation & Alternatives](#investigation--alternatives)
    19  - [Unresolved Questions](#unresolved-questions)
    20  
    21  ## Introduction
    22  
    23  One para explanation of the proposal that helps others get the brief info of this design doc.
    24  
    25  ## Motivation or Background
    26  
    27  What's the background and the problem being solved by this design doc? What use cases does it support?
    28  
    29  Please pay attention to this section. When a design is under review, the reviewers usually do not rush into details, but try to figure out the motivation or background of it. In other words, who wants the feature or what problem the feature solves.
    30  
    31  ## Detailed Design
    32  
    33  Explain the design in enough detail that: it is reasonably clear how the feature would be implemented, corner cases are dissected by example, how the feature is used, etc.
    34  
    35  It's better to describe the pseudo-code of the key algorithm, API interfaces, the UML graph, what components are needed to be changed in this section.
    36  
    37  Compatibility is important, please also take into consideration, a checklist:
    38  
    39  - Compatibility with other features
    40  - Compatibility with other internal components, like owner, processor, sink, etc.
    41  - Compatibility with other external components, like PD, TiKV, TiDB, TiUP, K8s, etc.
    42  - Upgrade compatibility
    43  - Downgrade compatibility
    44  
    45  ## Test Design
    46  
    47  A brief description of how the implementation will be tested. Both the integration test and the unit test should be considered.
    48  
    49  ### Functional Tests
    50  
    51  It's used to ensure the basic feature function works as expected. Both the integration test and the unit test should be considered.
    52  
    53  ### Scenario Tests
    54  
    55  It's used to ensure this feature works as expected in some common scenarios.
    56  
    57  ### Compatibility Tests
    58  
    59  A checklist to test compatibility:
    60  
    61  - Compatibility with other features
    62  - Compatibility with other internal components, like owner, processor, sink, etc.
    63  - Compatibility with other external components, like PD, TiKV, TiDB, TiUP, K8s, etc.
    64  - Upgrade compatibility
    65  - Downgrade compatibility
    66  
    67  ### Benchmark Tests
    68  
    69  The following two parts need to be measured:
    70  
    71  - The performance of this feature under different parameters
    72  - The performance influence on the online workload
    73  
    74  ## Impacts & Risks
    75  
    76  Describe the potential impacts & risks of the design on overall performance, security, k8s, and other aspects. List all the risks or unknowns by far.
    77  
    78  Please describe impacts and risks in two sections: Impacts could be positive or negative, and intentional. Risks are usually negative, unintentional, and may or may not happen. E.g., for performance, we might expect a new feature to improve latency by 10% (expected impact), there is a risk that latency in scenarios X and Y could degrade by 50%.
    79  
    80  ## Investigation & Alternatives
    81  
    82  How do other systems solve this issue? What other designs have been considered and what is the rationale for not choosing them?
    83  
    84  ## Unresolved Questions
    85  
    86  What parts of the design are still to be determined?