github.com/wmuizelaar/kpt@v0.0.0-20221018115725-bd564717b2ed/docs/design-docs/00-template.md (about)

     1  # Title
     2  
     3  * Author(s): \<your name\>, \<your github alias\>
     4  * Approver: \<kpt-maintainer\>
     5  
     6  >    Every feature will need design sign off an PR approval from a core
     7  >    maintainer.  If you have not got in touch with anyone yet, you can leave
     8  >    this blank and we will try to line someone up for you.
     9  
    10  ## Why
    11  
    12  Please provide a reason to have this feature.  For best results a feature should
    13  be addressing a problem that is described in a github issue.  Link the issues
    14  in this section.  The more user requests are linked here the more likely this
    15  design is going to get prioritized on the roadmap.
    16  
    17  It's good to include some background about the problem, but do not use that as a
    18  substitute for real user feedback.
    19  
    20  ## Design
    21  
    22  Please describe your solution. Please list any:
    23  
    24  * new config changes
    25  * interface changes
    26  * design assumptions
    27  
    28  For a new config change, please mention:
    29  
    30  * Is it backwards compatible? If not, what is the migration and deprecation 
    31    plan?
    32  
    33  
    34  ## User Guide
    35  
    36  This section should be written in the form of a detailed user guide describing 
    37  the user journey. It should start from a reasonable initial state, often from 
    38  scratch (Instead of starting midway through a convoluted scenario) in order 
    39  to provide enough context for the reader and demonstrate possible workflows. 
    40  This is a form of DDD (Documentation-Driven-Development), which is an effective 
    41  technique to empathize with the user early in the process (As opposed to 
    42  late-stage user-empathy sessions).
    43  
    44  This section should be as detailed as possible. For example if proposing a CLI 
    45  change, provide the exact commands the user needs to run, along with flag 
    46  descriptions, and success and failure messages (Failure messages are an 
    47  important part of a good UX). This level of detail serves two functions:
    48  
    49  It forces the author and the readers to explicitly think about possible friction
    50  points, pitfalls, failure scenarios, and corner cases (“A measure of a good 
    51  engineer is not how clever they are, but whether they think about all the 
    52  corner cases”). Makes it easier to author the user-facing docs as part of the 
    53  development process (Ideally as part of the same PR) as opposed to it being an 
    54  afterthought.
    55  
    56  ## Open Issues/Questions
    57  
    58  Please list any open questions here in the following format:
    59  
    60  ### \<Question\>
    61  
    62  Resolution: Please list the resolution if resolved during the design process or
    63  specify __Not Yet Resolved__
    64  
    65  ## Alternatives Considered
    66  
    67  If there is an industry precedent or alternative approaches please list them 
    68  here as well as citing *why* you decided not to pursue those paths.
    69  
    70  ### \<Approach\>
    71  
    72  Links and description of the approach, the pros and cons identified during the 
    73  design.
    74  
    75  # Review Process
    76  
    77  Design doc creators should raise the pull request similar to [this](https://github.com/GoogleContainerTools/kpt/pull/2576).
    78  Please name your documents with the design document number.  Pick n+1 from what's currently merged knowing that a slight
    79  renaming might need to happen if multiple design docs get accepted simultaneously.
    80  Please keep the name of the design doc in lower case with dashes in between words.
    81  
    82  Reviewers are auto-assigned to review the PR. Optionally, doc owner can mention any
    83  specific reviewers on the PR description. The turn around time for each review cycle
    84  on the PR from kpt maintainers is 1-2 days. After maintainers add comments to the PR,
    85  doc owner should respond to each of those comments and hit `Resolve conversation` button on the 
    86  comment thread. Once all the comments are resolved, design doc creator should hit `Re-request review`
    87  icon next to each reviewers' avatar in reviewers section. Reviewers will then be notified and, they will go through the
    88  resolved comments and might reopen the comment threads, and the cycle continues.
    89  Once all the reviewers approve the PR, it will be merged by the maintainers.
    90  Any design doc PRs which are not attended by the doc creators for more than 2 weeks will be closed.