Merge pull request #59 from prometheus/ci

fix: Make the check to actually fail on not formatted/broken links; fix PROM-52 proposal

Author: bwplotka

.github/.mdox.validator.yaml

@@ -3,4 +3,4 @@ version: 1
 # Don't check external URLs, currently it can timeout a lot on CI.
 validators:
   - type: ignore
-    regex: https://.*
+    regex: http(s|)://.*

0000-template.md

@@ -69,5 +69,5 @@ The section stating potential alternatives. Highlight the objections reader shou
 
 The tasks to do in order to migrate to the new idea.
 
-* [ ] Task one <GH issue>
-* [ ] Task two <GH issue> ...
+* [ ] Task one `<GH issue>`
+* [ ] Task two `<GH issue>` ...

Makefile

@@ -1,7 +1,6 @@
 include .bingo/Variables.mk
 
-.DEFAULT_GOAL := fmt
-MD_FILES_TO_FORMAT=$(shell find . -name "*.md")
+MD_FILES_TO_FORMAT=$(shell find . -name "*.md" | grep -v ".bingo/README.md")
 
 help: ## Displays help.
 	@awk 'BEGIN {FS = ":.*##"; printf "\nUsage:\n  make \033[36m<target>\033[0m\n\nTargets:\n"} /^[a-zA-Z_-]+:.*?##/ { printf "  \033[36m%-10s\033[0m %s\n", $$1, $$2 }' $(MAKEFILE_LIST)
@@ -10,10 +9,12 @@ help: ## Displays help.
 fmt: ## Format docs, ensure GitHub format.
 fmt: $(MDOX)
 	@echo "Formatting markdown files..."
-	$(MDOX) fmt --soft-wraps $(MD_FILES_TO_FORMAT)
+	$(MDOX) fmt --soft-wraps --links.validate --links.validate.config-file=.github/.mdox.validator.yaml $(MD_FILES_TO_FORMAT)
 
 .PHONY: check
 check: ## Checks if doc is formatter and links are correct (don't check external links).
 check: $(MDOX)
-	@echo "Checking markdown files. If changes are detected, try running `make` and trying again."
-	$(MDOX) fmt --soft-wraps --check --links.validate.config-file=.github/.mdox.validator.yaml *.md $(MD_FILES_TO_FORMAT)
+	@echo "Checking markdown file formatting and basic links."
+	$(MDOX) fmt --soft-wraps --links.validate --links.validate.config-file=.github/.mdox.validator.yaml --check $(MD_FILES_TO_FORMAT) || (echo "🔥 Validation failed, files not formatted or links are broken. Try running 'make fmt' to fix formatting!" && exit 1)
+	@echo "✅ Markdown files correctly formatted"
+	bash ./scripts/proposals-filename-check.sh

README.md

@@ -29,9 +29,9 @@ The process of proposing a change via a design document is the following:
 
 1. Fork `github.com/prometheus/proposals`.
 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. 
+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.
+   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.

SECURITY.md

@@ -3,4 +3,4 @@
 The Prometheus security policy, including how to report vulnerabilities, can be
 found here:
 
-<https://prometheus.io/docs/operating/security/>
+https://prometheus.io/docs/operating/security/

proposals/0001-proposal-process.md

@@ -62,7 +62,7 @@ I propose to host in git only accepted proposals, simply in the root directory.
 Given that, the process of proposing change with the design doc would look as follows (we can use the below text as the initial instruction):
 
 1. Fork `github.com/prometheus/proposals`.
-2. Create a GitHub Pull Request with a design document in markdown format to the repository's root directory. Make sure to use [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 doc) as the prefix and some unique name as the suffix in the file name.
+2. Create a GitHub Pull Request with a design document in markdown format to the repository's root directory. Make sure to use [template](../0000-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 doc) as the prefix and some unique name as the suffix in the file name.
    1. If you prefer Google Docs to any other collaboration tool, feel free to use it in the initial state. We recommend [Open Source Design Doc Template](https://docs.google.com/document/d/1zeElxolajNyGUB8J6aDXwxngHynh4iOuEzy3ylLc72U/edit#). However, the approval process will only happen officially in the Pull Request.
 3. Automatic formatter is enabled in the repository. Use `make` locally to format it. Use `make check` to check all links (will be done on the CI too).
 4. The design is accepted if the PR is merged into this repository. It's ok to eventually decide to reject the proposal and close the PR with meaningful reasons for why it was rejected.

proposals/0002-am-secure-cluster.md

@@ -8,7 +8,7 @@
 * **Related Issues and PRs:**
   * https://github.com/prometheus/alertmanager/pull/2237
 
-> NOTE(bwplotka): This proposal was moved from [Alertmanager repo](https://github.com/prometheus/alertmanager/blob/6ef6e6868dbeb7984d2d577dd4bf75c65bf1904f/doc/design/secure-cluster-traffic.md) before we had [unified proposal process](2022-11-23-proposal-process.md), so it does not follow consistent style guide. For new proposal see [README](/README.md).
+> NOTE(bwplotka): This proposal was moved from [Alertmanager repo](https://github.com/prometheus/alertmanager/blob/6ef6e6868dbeb7984d2d577dd4bf75c65bf1904f/doc/design/secure-cluster-traffic.md) before we had [unified proposal process](0001-proposal-process.md), so it does not follow consistent style guide. For new proposal see [README](/README.md).
 
 ## Status Quo
 

proposals/0028-utf8.md

@@ -94,10 +94,10 @@ We propose the following change in syntax to PromQL and the exposition format:
 * Quoted label name: `{"my.dotted.metric", "http.status"=~"5.."}`
 
 * Classic metrics do not need to be treated differently:
-`sum(rate(regular_metric{region="east"}[5m]))`
+  `sum(rate(regular_metric{region="east"}[5m]))`
 
 * If the user decides to put a classic metric inside the selector, it still needs to be quoted:
-`sum(rate({"regular_metric", region="east"}[5m]))`
+  `sum(rate({"regular_metric", region="east"}[5m]))`
 
 * Escape syntax if the metric has a quote: `sum(rate({"my \"quoted\" metric", region="east"}[5m]))` or use single quotes in PromQL (not available in the exposition format): `sum(rate({'my "quoted" metric', region="east"}[5m]))`
 
@@ -109,7 +109,7 @@ We propose the following change in syntax to PromQL and the exposition format:
   `{"my.metric.with.periods", region="east"}.sum`
 
 * Compatible with possible future metric name operator syntax via prefixes (not being proposed here):
-  ```{~`a\.regex.*selector.*`, region="east"}``` or `{!"not.this.name", region="east"}`
+  `{~`a\.regex.*selector.*`, region="east"}` or `{!"not.this.name", region="east"}`
 
 ### Unusual / Complex Characters
 
@@ -126,8 +126,8 @@ Templating is used in alerts, and for dashboards that want to reference metric v
 There a few situations where we need to consider backwards compatibility:
 
 1. Old metrics provider, new backend: Old providers will not serve UTF-8 metric names, so nothing needs to be done here.
-2. New metrics provider, old backend: Old versions of Prometheus will throw an error if they see the new syntax. Therefore we [propose a way](#Scrape-time) for the scraped target to serve previously-invalid metrics in a form that the old database can process.
-3. New backend, old query client: Errors will occur if an old client is fed UTF-8 metric names. Therefore we must [provide a way](#Text-escaping) for Prometheus to escape metric names such that old clients can query for and read them.
+2. New metrics provider, old backend: Old versions of Prometheus will throw an error if they see the new syntax. Therefore we [propose a way](#scrape-time) for the scraped target to serve previously-invalid metrics in a form that the old database can process.
+3. New backend, old query client: Errors will occur if an old client is fed UTF-8 metric names. Therefore we must [provide a way](#text-escaping) for Prometheus to escape metric names such that old clients can query for and read them.
 4. Old backend, new query client: as with the first case, nothing needs to be done.
 
 ### Text escaping
@@ -139,15 +139,15 @@ We propose an escaping syntax for metric names that contain UTF-8 characters for
 * All pre-existing underscores will become doubled: `__`.
 * If a string should start with "U__" already, it will need to be escaped: `U___55_____`. (That's `U__` + `_55_` (for `U`) + `__` + `__`).
 
-#### Mixed-Block Scenario 
+#### Mixed-Block Scenario
 
 We must consider an edge case in which a newer client persists metrics to disk in an older database that does not support UTF-8. Those metrics will be written to disk with the U__ escaping format. If, later, the user upgrades their database software, new metrics will be written with the native UTF-8 characters. At query time, there will be a problem: newer blocks were written with UTF-8 and older blocks were written with the escaping format. The query code will not know which encoding to look for.
 
 To avoid this confusion we propose to bump the version number in the tsdb meta.json file. On a per-block basis the query code can check the version number and look for UTF-8 metric names in native encoding for bumped version number 2, or in U__-escaped naming for earlier version 1.
 
 Additionally, this means that an old metric or label name containing a valid escape sequence by chance would be parsed differently after enabling UTF-8 support. For example, a metric called `U___263a_` would appear as `☺` after the upgrade (if read from an old storage chunk, scraped from an old target, or received from an old remote-write client). This is an extremely unlikely scenario in practice so we believe a theoretically possible implicit name change is acceptable.
 
-Lastly, if a metric is written as "U__" but does not pass the unescaping algorithm, then we assume it was meant to be read as-is and let it pass through. 
+Lastly, if a metric is written as "U__" but does not pass the unescaping algorithm, then we assume it was meant to be read as-is and let it pass through.
 
 ### Scrape Time
 
@@ -169,7 +169,7 @@ The HTTP endpoints will need to support HTTP-unquoting metric names in the URL p
 
 ## Implementation
 
-Implementing this feature will require updates to several Prometheus libraries. These updates will be written so that functionality does not change for existing users and builds, and will only be enabled when certain flags are flipped or options turned on. There will be minimal read-only backwards compatibility for clients that do not support the new supported character set and syntax. 
+Implementing this feature will require updates to several Prometheus libraries. These updates will be written so that functionality does not change for existing users and builds, and will only be enabled when certain flags are flipped or options turned on. There will be minimal read-only backwards compatibility for clients that do not support the new supported character set and syntax.
 
 This implementation summary is based on the partial proof-of-concept work and may need to expand to accommodate any additional edge cases that are encountered. We do not expect the scope of work to expand significantly.
 
@@ -219,11 +219,11 @@ We will also have to bump the version number of tsdb and add code to handle the
 
 While this syntax could be made to work with simple additional characters like dots, it does not fulfill the goal of full UTF-8 support, which would include `{` or other special characters without a verbose and less-readable escaping mechanism, e.g.
 
-  `my.dotted.metric\{with\ braces\ and\ spaces\}{foo="bar"}`.
+`my.dotted.metric\{with\ braces\ and\ spaces\}{foo="bar"}`.
 
 Versus our selected approach:
 
-  `{"my.dotted.metric{with braces and spaces}", foo="bar"}`
+`{"my.dotted.metric{with braces and spaces}", foo="bar"}`
 
 Selecting this approach would introduce a convenient syntax for only a small new subset of UTF-8, so a quoting mechanism would still be needed for the full character set. Rather than implement this half-improvement we decided to only support a full quoting approach.
 
@@ -239,7 +239,7 @@ See the [Discussion Doc](https://docs.google.com/document/d/1yFj5QSd1AgCYecZ9EJ8
 
 ### Backticked metric names outside the curly braces
 
-``` `my.dotted.metric`{"label"="value"}```
+` `my.dotted.metric`{"label"="value"}`
 
 Single, double, and backtick quotes are nearly equivalent in PromQL so this would just be the same as the above approach, or require changing the meaning of a particular quote character in a way that would break backward-compatibility. (Backticks prevent processing of escape sequences, which is otherwise enabled, see [PromQL documentation](https://prometheus.io/docs/prometheus/latest/querying/basics/#string-literals) for details.)
 
@@ -260,4 +260,3 @@ By allowing non-escaped characters, this approach risks colliding with any new f
 2. Make updates to Prometheus and Grafana Agent.
 3. Launch as experimental feature, default off.
 4. Once stable and debugged, make UTF-8 the default (with fallback escaping for old clients always supported).
-

proposals/0030-utf8-migration.md

@@ -48,7 +48,7 @@ The solution described here is valid for all forms of metrics ingestion, may it
 We must consider edge cases in which a blocks database has persisted metrics or labels that may have been written by different versions of code.
 There are multiple ways this can (and will) happen:
 
-* An older version of Prometheus ingests names from a newer metrics producer. In this case, names would be escaped with any of the available escaping methods.  If Prometheus is upgraded, newer blocks will be written in UTF-8.
+* An older version of Prometheus ingests names from a newer metrics producer. In this case, names would be escaped with any of the available escaping methods. If Prometheus is upgraded, newer blocks will be written in UTF-8.
 * A newer Prometheus receives names from an older producer, which is later upgraded. In this case, older names might be escaped using the replace-with-underscores method, and newer names will be UTF-8. This will often happen when Prometheus is receiving Open Telemetry metrics.
 * A newer Prometheus receives names from a mix of new and old producers, in which case the same block could contain escaped and UTF-8 data representing the same intended names.
 
@@ -96,7 +96,7 @@ We propose to do this by expanding a lookup for a UTF-8 metric or label name int
 
 1. **UTF-8**
 2. **underscore-replaced**: All unsupported characters are converted to underscores.
-3. **U__ escaping**:  As described in the UTF-8 proposal, strings with invalid characters can be escaped by prepending `U__` and replacing all invalid characters with `_[UTF8 value]_`.
+3. **U__ escaping**: As described in the UTF-8 proposal, strings with invalid characters can be escaped by prepending `U__` and replacing all invalid characters with `_[UTF8 value]_`.
 4. **[Datadog proxy](https://github.com/grafana/mimir-proxies/blob/main/pkg/datadog/ddprom/naming.go#L30-L34) escaping pattern**: "`.`" becomes "`_dot_`" and "`_`" becomes "`__`".
 
 In PromQL, the expansion would look something like this under the hood:
@@ -123,7 +123,7 @@ We will do performance testing to identify possible issues.
 
 If the user is querying for metrics using a regex lookup for the `__name__` label, attempting to rewrite that query to account for other name encodings would be overly complex and error-prone.
 Therefore we will not try to rewrite the regex to account for multiple escaping methods and the regex will be passed through as-is.
-Users will need to write custom regex queries to account for metric name changes during the transition period in this case. 
+Users will need to write custom regex queries to account for metric name changes during the transition period in this case.
 Since regex queries on metrics names are relatively rare and the domain of advanced users, we feel this is an acceptable approach.
 
 ### Name Collisions
@@ -178,4 +178,4 @@ That way queries for both the native UTF-8 name and the escaped name would succe
 When the migration was complete, users could turn off double-writing and only write UTF-8.
 
 This approach would cause an explosion of on-disk usage.
-As disk is one of the most expensive resources, this approach was quickly discarded.
+As disk is one of the most expensive resources, this approach was quickly discarded.