sigs.k8s.io/kubebuilder/v3@v3.14.0/designs/template.md (about)

     1  | Authors       | Creation Date | Status      | Extra |
     2  |---------------|---------------|-------------|---|
     3  | @name | date | Implementeble | - |
     4  
     5  Title of the Design/Proposal
     6  ===================
     7  
     8  <!-- Describe your change here.  This is purposefully freeform: we want
     9  enough information to evaluate the design, but not so much that you're
    10  annoyed by the overall design process and decide to bake cookies instead.
    11  -->
    12  
    13  ## Example
    14  
    15  <!-- Specify an example of how the user would use this.  It helps other
    16  contributors get a feel for how this will look in real code, and provides
    17  a good opportunity to evaluate the end-user feel of the code for yourself.
    18  
    19  If you find yourself groaning at verbosity, copy-and-pasting a lot, or
    20  writing a bunch of tiny helper functions, it's a good indication that you
    21  might need to re-evaluate the user experience of your design.
    22  
    23  This is also a good opportunity to stop and write a proof-of-concept, if
    24  you haven't already, which should help catch practical nits with the
    25  design. -->
    26  
    27  ## Open Questions [optional]
    28  
    29  <!-- This is where to call out areas of the design that require closure before deciding
    30  to implement the design.  For instance,
    31  > 1. This requires exposing previously private resources which contain sensitive
    32       information.  Can we do this?
    33  -->
    34  
    35  ## Summary
    36  
    37  <!-- The `Summary` section is incredibly important for producing high quality
    38  user-focused documentation such as release notes or a development roadmap. It
    39  should be possible to collect this information before implementation begins in
    40  order to avoid requiring implementers to split their attention between writing
    41  release notes and implementing the feature itself.
    42  
    43  A good summary is probably at least a paragraph in length.-->
    44  
    45  ## Motivation
    46  
    47  <!-- This section is for explicitly listing the motivation, goals and non-goals of
    48  this proposal. Describe why the change is important and the benefits to users.-->
    49  
    50  ### Goals
    51  
    52  <!-- List the specific goals of the proposal. How will we know that this has succeeded?-->
    53  
    54  ### Non-Goals
    55  
    56  <!-- What is out of scope for this proposal? Listing non-goals helps to focus discussion
    57  and make progress.-->
    58  
    59  ## Proposal
    60  
    61  <!-- This is where we get down to the nitty gritty of what the proposal actually is. -->
    62  
    63  ### User Stories
    64  
    65  <!-- Detail the things that people will be able to do if this is implemented.
    66  Include as much detail as possible so that people can understand the "how" of
    67  the system. The goal here is to make this feel real for users without getting
    68  bogged down.
    69  
    70  User story examples
    71  - As a user, I want to link the credit card to my profile so that I can pay for a rent faster, easier and without cash.
    72  - As a service provider, I want to add photos of my vehicles in the application so that I can attract more users.
    73  - As a user, I want several available vehicles to be displayed so that I can choose the most suitable option for me.
    74  
    75  - As a <role> I can <capability>, so that <receive benefit> -->
    76  
    77  ### Implementation Details/Notes/Constraints [optional]
    78  
    79  <!-- What are the caveats to the implementation? What are some important details that
    80  didn't come across above. Go in to as much detail as necessary here. This might
    81  be a good place to talk about core concepts and how they relate. -->
    82  
    83  ### Risks and Mitigations
    84  
    85  <!-- What are the risks of this proposal and how do we mitigate. Think broadly. For
    86  example, consider both security and how this will impact the larger Operator Framework
    87  ecosystem.
    88  
    89  How will security be reviewed and by whom? How will UX be reviewed and by whom?
    90  
    91  Consider including folks that also work outside your immediate sub-project. -->
    92  
    93  ### Proof of Concept [optional]
    94  
    95  <!-- A demo showcasing a prototype of your design can be extremely useful to the
    96  community when reviewing your proposal. There are many services that enable
    97  you to record and share demos. Most OLM features can be showcased from the
    98  command line, making [https://asciinema.org](https://asciinema.org) an
    99  excellent option to [record](https://asciinema.org/docs/usage) and
   100  [embed](https://asciinema.org/docs/embedding) your demo.
   101  
   102  Be sure to include:
   103  - An embedded recording of the prototype in action.
   104  - A link to the repository hosting the changes that the prototype introduces. -->
   105  
   106  ## Drawbacks
   107  
   108  <!-- The idea is to find the best form of an argument why this enhancement should _not_ be implemented. -->
   109  
   110  ## Alternatives
   111  
   112  <!-- Similar to the `Drawbacks` section the `Alternatives` section is used to
   113  highlight and record other possible approaches to delivering the value proposed
   114  by an enhancement. -->