From 224f6c4e9235524b185671e8939aa4a9abbeeec3 Mon Sep 17 00:00:00 2001 From: bwplotka Date: Fri, 9 May 2025 09:25:54 +0100 Subject: [PATCH 1/3] proposal: PROM- Proposal Referencing Signed-off-by: bwplotka --- 0000-00-00_template.md => 0000-template.md | 0 README.md | 10 ++-- proposals/0053-proposal-ids.md | 60 ++++++++++++++++++++++ 3 files changed, 66 insertions(+), 4 deletions(-) rename 0000-00-00_template.md => 0000-template.md (100%) create mode 100644 proposals/0053-proposal-ids.md diff --git a/0000-00-00_template.md b/0000-template.md similarity index 100% rename from 0000-00-00_template.md rename to 0000-template.md diff --git a/README.md b/README.md index 6031825a..cfbb45d2 100644 --- a/README.md +++ b/README.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-.md` where `` 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-`. +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. diff --git a/proposals/0053-proposal-ids.md b/proposals/0053-proposal-ids.md new file mode 100644 index 00000000..58401f07 --- /dev/null +++ b/proposals/0053-proposal-ids.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-. 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 `-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-`. This number is captured in the file name and it origins from the ID of the Pull Request that was used to approve and merge the proposal. + +We propose to NOT add stable number of digits in the official referencing. However, we propose we DO add 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- (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 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 existing proposal's file to have its PROM-; Leave the old files with a link to a new file, so the old links work. From 896e67e405b5e07ace66aceac6eebae844aed69a Mon Sep 17 00:00:00 2001 From: Bartlomiej Plotka Date: Mon, 12 May 2025 08:33:03 +0100 Subject: [PATCH 2/3] Apply suggestions from code review Co-authored-by: Arve Knudsen Signed-off-by: Bartlomiej Plotka --- proposals/0053-proposal-ids.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/proposals/0053-proposal-ids.md b/proposals/0053-proposal-ids.md index 58401f07..fc619d19 100644 --- a/proposals/0053-proposal-ids.md +++ b/proposals/0053-proposal-ids.md @@ -31,9 +31,9 @@ Goals and use cases for the solution as proposed in [How](#how): ## How -We propose every Prometheus proposal has a stable reference/ID in the form of the `PROM-`. This number is captured in the file name and it origins from the ID of the Pull Request that was used to approve and merge the proposal. +We propose every Prometheus proposal has a stable reference/ID in the form of the `PROM-`. 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 stable number of digits in the official referencing. However, we propose we DO add 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). +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`. @@ -57,4 +57,4 @@ There are a few alternatives to the `PROM-` prefix e.g. The tasks to do in order to migrate to the new idea. * [X] Adjust template and proposal docs. -* [ ] Rename existing proposal's file to have its PROM-; Leave the old files with a link to a new file, so the old links work. +* [ ] Rename each existing proposal's file to have its PROM-; Leave the old files with a link to a new file, so the old links work. From bbbeb4baa8fbf903f6ab087d6e6af6da8fec8447 Mon Sep 17 00:00:00 2001 From: bwplotka Date: Tue, 13 May 2025 08:15:17 +0100 Subject: [PATCH 3/3] Added example from Ayoub Signed-off-by: bwplotka --- proposals/0053-proposal-ids.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/0053-proposal-ids.md b/proposals/0053-proposal-ids.md index fc619d19..a3821590 100644 --- a/proposals/0053-proposal-ids.md +++ b/proposals/0053-proposal-ids.md @@ -48,7 +48,7 @@ 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 and not suggesting proposals + * Short but NOT clearly unique for Prometheus (e.g. Python [PEPs](https://peps.python.org/)) and not suggesting proposals * PROMETHEUS- * A bit too long?