Merge pull request #1220 from cloudflare/docs

Update docs

Author: prymitive

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.
 

docs/configuration.md

@@ -71,28 +71,47 @@ 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, which 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.
 - `exclude` - list of file patterns to ignore when running checks.
   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