github.com/thanos-io/thanos@v0.32.5/docs/contributing/proposal-process.md (about)

     1  ---
     2  type: docs
     3  title: Proposal Process
     4  menu: contributing
     5  ---
     6  
     7  # Proposals Process
     8  
     9  If there is no problem, there is no need for changing anything, no need for a proposal. This might feel trivial, but we should first ask ourselves this question before even thinking about writing a proposal.
    10  
    11  It takes time to propose an idea, find consensus and implement more significant concepts, so let's not use the time before we feel it's worth it. Even good ideas sometimes have to wait for a good moment to discuss them.
    12  
    13  Let's assume the idea sounds interesting to you. Yet, some ideas are quick and trivial enough to not require a formal proposal. To learn if we need proposal, ask yourself a following questions:
    14  
    15  * Is the idea hard to explain in 10m?
    16  * Are there major unknowns?
    17  * Would the project benefit from documenting the rationales behind this decision?
    18  * Does it touch the key element of an important API?
    19  
    20  If any of this is yes, this idea might require a formal proposal. See full proposal process, visualised below:
    21  
    22  ![where](../img/thanos_proposal_flow.png)
    23  
    24  > Note: It's totally ok for your proposal to be rejected if the community feels the idea is not needed now or having gaps. Not all ideas are as good as it looks at the first glance, with less context. Sometimes it's not a good time for it either. It's better to explicitly oppose it than to ignore it and leave it in limbo.
    25  
    26  ## Why do we have a Proposal Process?
    27  
    28  See rationales in our [proposal for proposal process](../proposals-done/202106-proposals-process.md)
    29  
    30  ## Template:
    31  
    32  ## Your Proposal Title
    33  
    34  * **Owners:**
    35    * `<@author: single champion for the moment of writing>`
    36  
    37  * **Related Tickets:**
    38    * `<JIRA, GH Issues>`
    39  
    40  * **Other docs:**
    41    * `<Links…>`
    42  
    43  > TL;DR: Give a summary of what this document is proposing and what components it is touching.
    44  >
    45  > *For example: This design doc is proposing a consistent design template for “example.com” organization.*
    46  
    47  ## Why
    48  
    49  Provide a motivation behind the change proposed by this design document, give context.
    50  
    51  *For example: It’s important to clearly explain the reasons behind certain design decisions in order to have a consensus between team members, as well as external stakeholders. Such a design document can also be used as a reference and knowledge-sharing purposes. That’s why we are proposing a consistent style of the design document that will be used for future designs.*
    52  
    53  ### Pitfalls of the current solution
    54  
    55  What specific problems are we hitting with the current solution? Why it’s not enough?
    56  
    57  *For example, We were missing a consistent design doc template, so each team/person was creating their own. Because of inconsistencies, those documents were harder to understand, and it was easy to miss important sections. This was causing certain engineering time to be wasted.*
    58  
    59  ## Goals
    60  
    61  Goals and use cases for the solution as proposed in [How](#how):
    62  
    63  * Allow easy collaboration and decision making on design ideas.
    64  * Have a consistent design style that is readable and understandable.
    65  * Have a design style that is concise and covers all the essential information.
    66  
    67  ### Audience
    68  
    69  If this is not clear already, provide the target audience for this change.
    70  
    71  ## Non-Goals
    72  
    73  * Move old designs to the new format.
    74  * Not doing X,Y,Z.
    75  
    76  ## How
    77  
    78  Explain the full overview of the proposed solution. Some guidelines:
    79  
    80  * Make it concise and **simple**; put diagrams; be concrete, avoid using “really”, “amazing” and “great” (:
    81  * How you will test and verify?
    82  * How you will migrate users, without downtime. How we solve incompatibilities?
    83  * What open questions are left? (“Known unknowns”)
    84  
    85  ## Alternatives
    86  
    87  The section stating potential alternatives. Highlight the objections reader should have towards your proposal as they read it. Tell them why you still think you should take this path [[ref](https://twitter.com/whereistanya/status/1353853753439490049)]
    88  
    89  1. This is why not solution Z...
    90  
    91  ## Action Plan
    92  
    93  The tasks to do in order to migrate to the new idea.
    94  
    95  * [ ] Task one <gh issue="">
    96  
    97  * [ ] Task two <gh issue=""> ...