|
| 1 | +# 2021-06: Proposal Process |
| 2 | + |
| 3 | +* **Owners:**: |
| 4 | + * [`@bwplotka`](https://github.com/bwplotka) |
| 5 | + |
| 6 | +* **Other docs:** |
| 7 | + * [KEP Process](https://github.com/kubernetes/enhancements/blob/master/keps/README.md) |
| 8 | + * [Observability Team Process (Internal)](https://docs.google.com/document/d/1eojXStPdq1hYwv36pjE-vKR1q3dlBbpIx5w_L_v2gNo/edit) |
| 9 | + |
| 10 | +> TL;DR: We would like to propose an improved, official proposal process for Monitoring Group that clearly states when, where and how to create proposal/enhancement/design documents. |
| 11 | +
|
| 12 | +## Why |
| 13 | + |
| 14 | +More extensive architectural, process, or feature decisions are hard to explain, understand and discuss. It takes a lot of time to describe the idea, to motivate interested parties to review it, give feedback and approve. That's why it is essential to streamline the proposal process. |
| 15 | + |
| 16 | +Given that we work in highly distributed teams and work with multiple communities, we need to allow asynchronous discussions. This means it's essential to structure the talks into shared documents. Persisting in those decisions, once approved or rejected, is equally important, allowing us to understand previous motivations. |
| 17 | + |
| 18 | +There is a common saying [`"I've just been around long enough to know where the bodies are buried"`](https://twitter.com/AlexJonesax/status/1400103567822835714). We want to ensure the team related knowledge is accessible to everyone, every day, no matter if the team member is new or part of the team for ten years. |
| 19 | + |
| 20 | +### Pitfalls of the current solution |
| 21 | + |
| 22 | +Currently, the Observability Platform team have the process defined [here (internal)](https://docs.google.com/document/d/1eojXStPdq1hYwv36pjE-vKR1q3dlBbpIx5w_L_v2gNo/edit#heading=h.kpdg1wrd3pcc), whereas the In-Cluster part were not defining any official process ([as per here (internal)](https://docs.google.com/document/d/1vbDGcjMjJMTIWcua5Keajla9FzexjLKmVk7zoUc0_MI/edit#heading=h.n0ac5lllvh13)). |
| 23 | + |
| 24 | +In practice, both teams had somehow similar flow: |
| 25 | + |
| 26 | +* For upstream: Follow the upstream project's contributing guide, e.g Thanos |
| 27 | +* For downstream: |
| 28 | + * Depending on the size: |
| 29 | + * Small features can be proposed during the bi-weekly team-sync or directly in Slack. |
| 30 | + * If the team can reach consensus in this time, then document the decision somewhere written, e.g. an email, Slack message to which everyone can add an emoji reaction, etc. |
| 31 | + * Add a JIRA ticket to plan this work. |
| 32 | + * Large features might need a design doc: |
| 33 | + 1. Add a JIRA ticket for creating the design doc |
| 34 | + 2. Create a new Google Doc in the team folder based on [this template](https://docs.google.com/document/d/1ddl_dLxjoIvWQuRgLdzL2Gd1EX1mkJQUZ-rgUh-T4d8/edit) |
| 35 | + 3. Fill sections |
| 36 | + 4. Announce it on the team mailing list and Slack channel |
| 37 | + 5. Address comments / concerns 6 Define what "done" means for this proposal, i.e. what is the purpose of this design document: |
| 38 | + * Knowledge sharing / Brain dump: This kind of document may not need a thorough review or any official approval |
| 39 | + * Long term vision and Execution & Implementation: If approved (with LGTM comments, or in an approved section) by a majority of the team and no major concerns consider it approved. NOTE: The same applies to rejected proposals. |
| 40 | + 1. If the document has no more offline comments and no consensus was reached, schedule a meeting with interested parties. |
| 41 | + 2. When the document changes status, move it to the appropriate status folder in the design docs directory of the team folder. If an approved proposal concerns a component with its own directory, e.g. Telemeter, then create a shortcut to the proposal document in the component-specific directory. This helps us find design documents by topic and by status. |
| 42 | + |
| 43 | +It served us well, but it had the following issues (really similar to ones stated in [handbook proposal](../Accepted/202106-handbook.md#pitfalls-of-the-current-solution)): |
| 44 | + |
| 45 | +* Even if our Google Design docs organized in our team drive, those Google documents are not easily discoverable. |
| 46 | +* Existing Google doc-based documents are hard to consume. The formatting is widely different. Naming is inconsistent. |
| 47 | +* Document creation is rarely actionable. There is no review process, so the effort of creating a relevant document might be wasted, as the document is lost. This also leads to docs being in the half-completed state, demotivating readers to look at it. |
| 48 | +* It's hard to track previous discussions around proposals, who approved them (e.g. proposals). |
| 49 | +* It's not public, and it's hard to share good proposals with other external and internal teams. |
| 50 | + |
| 51 | +## Goals |
| 52 | + |
| 53 | +Goals and use cases for the solution as proposed in [How](#how): |
| 54 | + |
| 55 | +* Allow easy collaboration and decision making on design ideas. |
| 56 | +* Have a consistent design style that is readable and understandable. |
| 57 | +* Ensure design docs are discoverable for better awareness and knowledge sharing about past decisions. |
| 58 | +* Define a clear review and approval process. |
| 59 | + |
| 60 | +## Non-Goals |
| 61 | + |
| 62 | +* Define process for other documents (see [handbook proposal](../Accepted/202106-handbook.md#pitfalls-of-the-current-solution)) |
| 63 | + |
| 64 | +## How |
| 65 | + |
| 66 | +We want to propose an improved, official proposal process for Monitoring Group that clearly states *when, where and how* to create proposal/enhancement/design documents. |
| 67 | + |
| 68 | +Everything starts with a problem statement. It might be a missing functionality, confusing existing functionality or broken one. It might be an annoying process, performance or security issue (or potential one). |
| 69 | + |
| 70 | +### Where to Propose Changes/Where to Submit Proposals? |
| 71 | + |
| 72 | +As defined in [handbook proposal](../Accepted/202106-handbook.md#pitfalls-of-the-current-solution), our Handbook should tell you that Handbook is meant to be an index for our team resources and a linking point to other distributed projects we maintain or contribute to. |
| 73 | + |
| 74 | +First, we need to identify if the idea we have is something we can contribute to an upstream project, or it does not fit anywhere else, so we can leverage the [Handbok Proposal directory](..) and the [process](#handbook-proposal-process). See the below algorithm to find it out: |
| 75 | + |
| 76 | + |
| 77 | + |
| 78 | +[Internal Team Drive for Public and Confidential Proposals](https://drive.google.com/drive/folders/1WGqC3gMCxIQlrnjDUYfNUTPYYRI5Cxto) |
| 79 | + |
| 80 | +[Templates](../process.md#templates) |
| 81 | + |
| 82 | +### Handbook Proposal Process |
| 83 | + |
| 84 | +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. |
| 85 | + |
| 86 | +It takes time to propose an idea, find consensus and implement more significant concepts, so let's not waste time before it's worth it. But, unfortunately, even good ideas sometimes have to wait for a good moment to discuss them. |
| 87 | + |
| 88 | +Let's assume the idea sounds interesting to you; what to do next, where to propose it? How to review it? Follow the algorithm below: |
| 89 | + |
| 90 | + |
| 91 | + |
| 92 | +> Note: It's totally ok to reject a proposal if a team member feels the idea is wrong. It's better to explicitly oppose it than to ignore it and leave it in limbo. |
| 93 | +
|
| 94 | +> NOTE: We would love to host Logging and Tracing Teams if they choose to follow our process, but we don't want to enforce it. We are happy to extend this process from the Monitoring Group handbook to Observability Group. Still, it has to grow organically (if the Logging, Tracing team will see the value of joining us here). |
| 95 | +
|
| 96 | +## Alternatives |
| 97 | + |
| 98 | +1. Organize Team Google Drive with all Google docs we have. |
| 99 | + |
| 100 | +Pros: |
| 101 | +* Great for initial collaboration |
| 102 | + |
| 103 | +Cons: |
| 104 | +* Inconsistent format |
| 105 | +* Hard to track approvers |
| 106 | +* Never know when the doc is "completed." |
| 107 | +* Hard to maintain over time |
| 108 | +* Hard to share and reuse outside |
| 109 | + |
| 110 | +## Action Plan |
| 111 | + |
| 112 | +* [X] Explain process in [Proposal Process Guide](../process.md) |
| 113 | +* [ ] Move existing up-to-date public design docs over to the Handbook (deadline: End of July). |
| 114 | + * TIP: You can use [Google Chrome Plugin](https://workspace.google.com/marketplace/app/docs_to_markdown/700168918607) to convert Google Doc into markdown easily. |
| 115 | +* [ ] Propose a similar process to upstream projects that do not have it. |
0 commit comments