Merge pull request #53 from prometheus/proposal-ids

proposal: PROM-<number> Proposal Referencing

Author: bwplotka

0000-00-00_template.md renamed to 0000-template.md

@@ -28,10 +28,12 @@ Don’t get scared to propose ideas! It’s amazing to innovate in the open and
 The process of proposing a change via a design document is the following:
 
 1. Fork `github.com/prometheus/proposals`.
-2. Create a GitHub Pull Request with a design document in markdown format to the [proposals directory](./proposals). Make sure to use the [template](0000-00-00_template.md) as the guide for what sections should be present in the document. Put the creation date (the day you started preparing this design document) as the prefix and some unique name as the suffix in the file name. 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](https://docs.google.com/document/d/1zeElxolajNyGUB8J6aDXwxngHynh4iOuEzy3ylLc72U/edit#). However, the approval process will only happen officially in the Pull Request.
-3. 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).
-4. 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.
+2. Copy the [template](0000-template.md) to [proposals directory](./proposals) 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](https://docs.google.com/document/d/1zeElxolajNyGUB8J6aDXwxngHynh4iOuEzy3ylLc72U/edit#). 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](https://docs.google.com/document/d/11LC3wJcVk00l8w5P3oLQ-m3Y37iom6INAMEu2ZAGIIE/edit) or announce it to the [developer mailing list](https://groups.google.com/forum/#!forum/prometheus-developers) 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.

README.md

@@ -0,0 +1,60 @@
+## Proposal IDs
+
+* **Owners:**
+  * `@bwplotka`
+
+* **Implementation Status:** `Implemented`
+
+* **Related Issues and PRs:**
+  * https://github.com/prometheus/proposals/issues/51
+
+> TL;DR: We propose every Prometheus proposal has a stable reference/ID in the form of the PROM-<number>. The number is the PR ID from the original PR that was used to discuss and approve the proposal.
+
+## Why
+
+It's important to reference decisions made in the proposal in the following development (code, docs, discussions). Currently, we either have some tribal naming for a proposal, link to a proposal repo PR when proposal is not yet approved or GH link to the proposal file with that original `<date>-template.md`.
+
+We want to ensure that "link" is even more consistent, stable and short than the current approach.
+
+### Pitfalls of the current solution
+
+* We use inconsistent references (name, PR link, file link).
+* The references e.g. links are hard to use (e.g. mentioning in the code commentary) and hard to memorize.
+* The date in the file is usually misleading. It's a creation date vs approval date (the latter might be what we usually expect).
+* While we try to ensure links in the `proposal/` directory never change, there's a risk we break those one day.
+
+## Goals
+
+Goals and use cases for the solution as proposed in [How](#how):
+
+* Each proposal has a short, memorable and unique ID.
+
+## How
+
+We propose every Prometheus proposal has a stable reference/ID in the form of the `PROM-<number>`. This number is captured in the file name and it originates from the ID of the Pull Request that was used to approve and merge the proposal.
+
+We propose to NOT add a stable number of digits in the official referencing. However, we propose we DO add a stable number of digits in the file name, so the file browsing has a convenient ordering. We propose 4 digits for now, prefixed by zeros, which can be increased to 5 once we have PR numbers in ten-thousands (likely in a decade).
+ 
+For example, this proposal is referenced as `PROM-53`, because we proposed this in the [PR `#53`](https://github.com/prometheus/proposals/pulls/53). This proposal file name is then `0053-proposal-ids.md`.
+
+For the existing proposals, we propose to rename existing proposal's file to have its PROM-<number> (based on their initial PRs), but leave the old files with a link to a new file, so the old links work.
+
+## Alternatives
+
+### Different Prefixes
+
+There are a few alternatives to the `PROM-` prefix e.g.
+
+* PEP- ("Prometheus Enhancement Proposal")
+  * Consistent with K8s and Otel, but Prometheus community never used "EP" naming.
+* P- or PP- ("Prometheus Proposal")
+  * Short but NOT clearly unique for Prometheus (e.g. Python [PEPs](https://peps.python.org/)) and not suggesting proposals
+* PROMETHEUS-
+  * A bit too long?
+
+## Action Plan
+
+The tasks to do in order to migrate to the new idea.
+
+* [X] Adjust template and proposal docs.
+* [ ] Rename each existing proposal's file to have its PROM-<number>; Leave the old files with a link to a new file, so the old links work.