From 888ae5535fc1bba097cc9e78e7dc57634b518eb7 Mon Sep 17 00:00:00 2001
From: Lukasz Mierzwa <lukasz@cloudflare.com>
Date: Mon, 9 Dec 2024 11:21:01 +0000
Subject: [PATCH] Update docs

---
 docs/changelog.md     | 30 +++++++++++++++++++++++++++++-
 docs/configuration.md | 27 +++++++++++++++++++++++----
 2 files changed, 52 insertions(+), 5 deletions(-)

diff --git a/docs/changelog.md b/docs/changelog.md
index c8fda6ff..4f75b5ca 100644
--- a/docs/changelog.md
+++ b/docs/changelog.md
@@ -5,7 +5,10 @@
 ### Added
 
 - Added `schema` option to the `parser` configuration block for setting rule validation
-  schema. Default value is `prometheus` and tells pint to expect rules with the schema
+  schema. This option is only used when files are parsed in strict mode - which is when
+  rule file path does NOT match any of the `parser:relaxed` regex values or when simply
+  `parser:relaxed` is not set at all.
+  Default value is `prometheus` and tells pint to expect rule files with the schema
   expected by Prometheus itself. If you use pint to validate rules loaded into Thanos Rule
   component then set `schema` to `thanos` in your pint config file:
 
@@ -15,6 +18,31 @@
   }
   ```
 
+  File schema when using `schema: prometheus` (default):
+
+  ```yaml
+  groups:
+    - name: example
+      rules:
+        - record: ...
+          expr: ...
+        - alert: ...
+          expr: ...
+  ```
+
+  When using `schema: thanos`:
+
+  ```yaml
+  groups:
+    - name: example
+      partial_response_strategy: abort
+      rules:
+        - record: ...
+          expr: ...
+        - alert: ...
+          expr: ...
+  ```
+
 - Rules configured in `pint` config can now be locked - when a rule is locked it cannot
   be disabled by users by adding a `# pint disable ...` or `# pint snooze ...` comments.
 
diff --git a/docs/configuration.md b/docs/configuration.md
index 5dbadc64..eb564dac 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -71,13 +71,15 @@ parser {
 }
 ```
 
-- `schema` - rule file schema to use, valid values are `prometheus` and `thanos`.
-  Setting it to `prometheus` means that pint will assume that all rules have the schema
+- `schema` - rule file schema to use when using `strict` parser mode, valid values are `prometheus` and `thanos`.
+  This option is has no effect when `relaxed` mode is enabled, see below.
+  Setting it to `prometheus` means that pint will assume that all rule files have the schema
   as defined in [alerting rules](https://prometheus.io/docs/prometheus/latest/configuration/alerting_rules/)
   and [recording rules](https://prometheus.io/docs/prometheus/latest/configuration/recording_rules/)
   Prometheus docs.
   Setting it to `thanos` will tell pint to use the schema as defined
-  in [Thanos Rule](https://thanos.io/tip/components/rule.md/) docs.
+  in [Thanos Rule](https://thanos.io/tip/components/rule.md/) docs, whoich currently allows for setting
+  an extra key on the rule group object - `partial_response_strategy`.
   Default value is `prometheus`.
 - `include` - list of file patterns to check when running checks. Only files
   matching those regexp rules will be checked, other modified files will be ignored.
@@ -85,14 +87,31 @@ parser {
   This option takes precedence over `include`, so if a file path matches both
   `include` & `exclude` patterns, it will be excluded.
 - `relaxed` - by default, pint will parse all files in strict mode, where
-  all rule files must have the exact syntax Prometheus expects:
+  all rule files must have the exact syntax Prometheus or Thanos expects:
+
+  When using `schema: prometheus` (default):
+
+  ```yaml
+  groups:
+    - name: example
+      rules:
+        - record: ...
+          expr: ...
+        - alert: ...
+          expr: ...
+  ```
+
+  When using `schema: thanos`:
 
   ```yaml
   groups:
     - name: example
+      partial_response_strategy: abort
       rules:
         - record: ...
           expr: ...
+        - alert: ...
+          expr: ...
   ```
 
   If you're using pint to lint rules that are embedded inside a different structure