Proposals

This repository holds all the past and current proposals for the Prometheus Ecosystem. It’s the single place for reviewing, discovering, and working on the design documents. It is also a record of past decisions and approvals.

Current Proposals

• The open PRs with the proposal label show all the pending proposals.
• The proposals directory shows all the accepted proposals. See the “Implementation Status” for details on the implementation.
• The PRs with the proposal label that are closed without merging show all the rejected proposals.

What’s a Design Document?

It’s essential to clearly explain the reasons behind certain design decisions to have a community consensus. This is especially important in Prometheus, where every decision might have a significant impact given the high adoption and stability of the software and standards we work on.

In our world, no decision is perfect, so having a design document explaining our trade-offs is essential. Such a document can also be used later as a reference and for knowledge-sharing purposes.

Design documents do not always reflect what has been (or will be) implemented. Implementation details might have changed since a feature was merged. Design docs are not considered documentation and can not define a standard. Instead, it should explain the motivation, scope, decisions, and alternatives considered.

Proposal Process

Don’t get scared to propose ideas! It’s amazing to innovate in the open and get feedback on ideas.

The process of proposing a change via a design document is the following:

1. Fork github.com/prometheus/proposals.
2. Copy the template to proposals directory as ./proposals/0000-<my-proposal>.md where <my-proposal> is the relevant proposal title. Once a Pull Request is made, update the prefix number to match the PR ID. As a result your proposal will be referenced as PROM-<PR ID>.
3. Fill the proposal details. Use the template as the guide for what sections should be present in the document.
4. Create a GitHub Pull Request with the proposal, using proposal: prefix in the PR Title. Once the PR is proposed, a maintainer will assign a proposal label.
   1. If you prefer Google Docs to any other collaboration tool, feel free to use it in the initial state. We recommend the Open Source Design document Template. However, the approval process will only happen officially in the Pull Request.
5. An automatic formatter is enabled in the repository. Use make locally to trigger the formatting of all markdown documents (requires a working Go environment). Use make check to check all links (will be done by the CI pipeline, too).
6. After a sufficient amount of discussion, the Prometheus team will try to reach a consensus of accepting or rejecting the proposal. In the former case, the PR gets merged. In the latter case, the PR gets closed with meaningful reasons why the proposal was rejected.
   1. If more eyes are needed or no consensus was made: Propose your idea as an agenda item for the Prometheus DevSummit or announce it to the developer mailing list to gather more information. You are welcome to start working on the design document before a bigger discussion—it is often easier to discuss with prior details provided. Be prepared that the idea might be rejected later. Still, the record of the document in the Pull Request is valuable even in a rejected state to inform about past decisions and opportunities considered.
   2. To merge the PR, we need approval (consensus) from the maintainers of the related component(s).
   3. Optionally: Find a sponsor among the Prometheus maintainers to get momentum on a change.

Once the PR gets merged, the design document can change, but it requires (less strict, but still) a PR with review and merge by a maintainer.