Added formal proposal process.

Signed-off-by: Bartlomiej Plotka <bwplotka@gmail.com>

CONTRIBUTING.md

@@ -21,7 +21,6 @@ Prometheus uses GitHub to manage reviews of pull requests.
 
 * Be sure to sign off on the [DCO](https://github.com/probot/dco#how-it-works).
 
-
 ## Steps to Contribute
 
 Should you wish to work on an issue, please claim it first by commenting on the GitHub issue that you want to work on it. This is to prevent duplicated efforts from contributors on the same issue.
@@ -46,6 +45,10 @@ We use [`golangci-lint`](https://github.com/golangci/golangci-lint) for linting
 
 All our issues are regularly tagged so that you can also filter down the issues involving the components you want to work on. For our labeling policy refer [the wiki page](https://github.com/prometheus/prometheus/wiki/Label-Names-and-Descriptions).
 
+## Proposals
+
+For bigger changes that requires consensus or research, please refer to Prometheus [proposal process](...).
+
 ## Pull Request Checklist
 
 * Branch from the main branch and, if needed, rebase to the current main branch before submitting your pull request. If it doesn't merge cleanly with main you may be asked to rebase your changes.

documentation/proposals/done/202106-proposals-process.md

@@ -0,0 +1,61 @@
+# 2021-06: Proposal Process
+
+* **Owners:**:
+  * [`@bwplotka`](https://github.com/bwplotka)
+
+* **Other docs:**
+  * [KEP Process](https://github.com/kubernetes/enhancements/blob/master/keps/README.md)
+  * [RHOBS Handbook Proposal Process](https://rhobs-handbook.netlify.app/proposals/done/202106-proposals-process.md/)
+  * [Thanos Proposal Process](https://deploy-preview-4366--thanos-io.netlify.app/tip/contributing/proposal-process.md/)
+
+> TL;DR: We would like to propose an improved, official proposal process for Prometheus that clearly states when, where and how to create proposal/enhancement/design documents. We propose to store done, accepted and rejected proposals in markdown in the main Prometheus repo.
+
+## Why
+
+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.
+
+Given that as open-source community 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 those decisions, once approved or rejected, is equally important, allowing us to understand previous motivations.
+
+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.
+
+### Pitfalls of the current solution
+
+Prometheus does not have official proposal process. The unofficial process is to create a proposal either in Google Doc or directly in GH issue or in dev mailing list. This inconsistency is leading to fragmentation of reviewers and process being overall not clear. This was the direct feedback of past Prometheus mentees.
+
+Specifically current flow has following disadventages:
+
+* Current pending proposals are hard to discover makes it harder for maintainers to follow up on them.
+* Past accepted / in limbo state / rejected proposals are impossible to track. This leads to
+  * Less value in creating such formal proposal.
+  * Repeated questions and researching on the idea that was previously researched.
+  * Lack of awareness of past motivations for the decision.
+* Not clear process makes it less likely for contributor to actually spend time on proper proposal for the desired idea.
+
+## Goals
+
+Goals and use cases for the solution as proposed in [How](#how):
+
+* Allow easy collaboration and decision making on design ideas.
+* Have a consistent design style that is readable and understandable.
+* Ensure design docs are discoverable for better awareness and knowledge sharing about past decisions.
+* Define a clear review and approval process.
+
+## Non-Goals
+
+* Define process for other type of documents.
+
+## How
+
+We want to propose an improved, official proposal process for Prometheus Community that clearly states *when, where and how* to create proposal/enhancement/design documents.
+
+See [the full proposed process and template defined here](../proposal-process.md)
+
+## Alternatives
+
+1. Put proposals in a separate repository in Prometheus org
+
+There is no harm in putting those in main repository. Spreading this info somewhere else will harm discoverability and IMO does not bring any additional value.
+
+2. Put proposals in a docs repository in Prometheus org and allow it to be part of prometheus.io website.
+
+In my opinion the website should be focused on users. It might be confusing and surprising for users to read past accepted / rejected proposals there.

documentation/proposals/proposal-process.md

@@ -0,0 +1,91 @@
+# Proposals Process
+
+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.
+
+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.
+
+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:
+
+* Is the idea hard to explain in 10m?
+* Are there major unknowns?
+* Would the project benefit from documenting the rationales behind this decision?
+* Does it touch the key element of an important API?
+
+If any of this is yes, this idea might require a formal proposal. See full proposal process, visualised below:
+
+![where](../images/prometheus_proposal_process.png)
+
+> 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.
+
+## Why do we have a Proposal Process?
+
+See rationales in our [proposal for proposal process](./done/202106-proposals-process.md)
+
+## Template:
+
+## Your Proposal Title
+
+* **Owners:**
+  * `<@author: single champion for the moment of writing>`
+
+* **Related Tickets:**
+  * `<JIRA, GH Issues>`
+
+* **Other docs:**
+  * `<Links…>`
+
+> TL;DR: Give a summary of what this document is proposing and what components it is touching.
+>
+> *For example: This design doc is proposing a consistent design template for “example.com” organization.*
+
+## Why
+
+Provide a motivation behind the change proposed by this design document, give context.
+
+*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.*
+
+### Pitfalls of the current solution
+
+What specific problems are we hitting with the current solution? Why it’s not enough?
+
+*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.*
+
+## Goals
+
+Goals and use cases for the solution as proposed in [How](#how):
+
+* Allow easy collaboration and decision making on design ideas.
+* Have a consistent design style that is readable and understandable.
+* Have a design style that is concise and covers all the essential information.
+
+### Audience
+
+If this is not clear already, provide the target audience for this change.
+
+## Non-Goals
+
+* Move old designs to the new format.
+* Not doing X,Y,Z.
+
+## How
+
+Explain the full overview of the proposed solution. Some guidelines:
+
+* Make it concise and **simple**; put diagrams; be concrete, avoid using “really”, “amazing” and “great” (:
+* How you will test and verify?
+* How you will migrate users, without downtime. How we solve incompatibilities?
+* What open questions are left? (“Known unknowns”)
+
+## Alternatives
+
+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)]
+
+1. This is why not solution Z...
+
+## Action Plan
+
+The tasks to do in order to migrate to the new idea.
+
+* [ ] Task one <gh issue="">
+
+* [ ] Task two <gh issue=""> ...