docs: opa-fmt v1/v0 notes

This explains the different behaviour of `opa fmt` between v0 and v1 when working with v0/v1 files in Rego. Signed-off-by: Charlie Egan <[email protected]>
StyraInc · Jan 14, 2025 · 9756afd · 9756afd
1 parent 351b5bb
commit 9756afd
Showing 1 changed file with 17 additions and 0 deletions.
diff --git a/docs/rules/style/opa-fmt.md b/docs/rules/style/opa-fmt.md
@@ -30,6 +30,23 @@ indent_style = tab
 indent_size = 4
 ```
 
+## OPA Format with Rego v1 and v0
+
+OPA 1.0 makes Rego v1 the default. This change mandated some changes to the
+functionality of the `opa fmt` command and a number of new options for working
+with mixed version code bases. See the
+[OPA documentation](https://www.openpolicyagent.org/docs/latest/cli/#opa-fmt)
+for the command's options.
+
+In Regal, a v0 file will have the `opa-fmt` violation unless it's been formatted
+with `opa fmt --v0-v1`. A v1 file will have the `opa-fmt` violation unless it's
+been formatted with `opa fmt` (the rego.v1 keyword is permitted but not added).
+
+When formatting, a file expected to be v1 based on the configuration, but with
+v0 syntax is still formatted as `opa fmt –-v0-v1`. Please see
+[Configuring Rego Version](https://docs.styra.com/regal#configuring-rego-version)
+for more configuration help for multi version projects.
+
 ## Configuration Options
 
 This linter rule provides the following configuration options: