diff --git a/docs/configuration/capabilities.md b/docs/configuration/capabilities.md index c7effcdf..36c34d65 100644 --- a/docs/configuration/capabilities.md +++ b/docs/configuration/capabilities.md @@ -3,16 +3,15 @@ By default, Regal will lint your policies using the [capabilities](https://www.openpolicyagent.org/docs/deployments/#capabilities) of the latest version of OPA known to Regal (i.e. the latest version of OPA at the time Regal was released). Sometimes you might want to tell Regal -that some rules aren't applicable to your project (yet!). As an example, if you're running OPA v0.46.0, you likely won't -be helped by the -[custom-has-key](https://openpolicyagent.org/projects/regal/rules/idiomatic/custom-has-key-construct) -rule, as it suggests using the `object.keys` built-in function introduced in OPA -v0.47.0. The opposite could also be true — -sometimes new versions of OPA will invalidate rules that applied to older versions. An example of this is the upcoming -introduction of `import rego.v1`, which will make -[implicit-future-keywords](https://openpolicyagent.org/projects/regal/rules/imports/implicit-future-keywords) -obsolete, as importing -`rego.v1` automatically imports all "future" functions. +that some rules aren't applicable to your project (yet!). For example, recommending the use of the +[strings.count](https://www.openpolicyagent.org/projects/regal/rules/idiomatic/use-strings-count) function doesn't make +much sense for users who for some reason are targeting a version of OPA before v0.67.0, as that's when that function was +introduced. + +The opposite could also be true — new versions of OPA sometimes invalidate rules that were relevant in the past. For +example, having Regal check for +[implicit future keyword](https://www.openpolicyagent.org/projects/regal/rules/imports/implicit-future-keywords) imports +makes no sense post OPA 1.0, as importing "future" keywords are no longer needed. Capabilities help you tell Regal which features to take into account, and rules with dependencies to capabilities not available or not applicable in the given version will be skipped. diff --git a/docs/rules/bugs/rule-named-if.md b/docs/rules/bugs/rule-named-if.md index 4860ca41..27044e2b 100644 --- a/docs/rules/bugs/rule-named-if.md +++ b/docs/rules/bugs/rule-named-if.md @@ -4,13 +4,12 @@ **Category**: Bugs -## Notice: Rule made obsolete by OPA 1.0 +## Notice: Rule disabled by default since OPA 1.0 -Since Regal v0.30.0, this rule is only enabled for projects that have either been explicitly configured to target -versions of OPA before 1.0, or if no configuration is provided — where Regal is able to determine that an older version -of OPA/Rego is being targeted. Consult the documentation on Regal's -[configuration](https://openpolicyagent.org/projects/regal#configuration) for information on how to best work with older versions of -OPA and Rego. +This rule is only enabled for projects that have either been explicitly configured to target versions of OPA before 1.0, +or if no configuration is provided — where Regal is able to determine that an older version of OPA/Rego is being +targeted. Consult the documentation on Regal's [configuration](https://openpolicyagent.org/projects/regal#configuration) +for information on how to best work with older versions of OPA and Rego. Since OPA v1.0, this rule is automatically disabled, as the parser itself will throw an error if a rule is named `if`, as that is made a keyword in Rego v1.0. diff --git a/docs/rules/idiomatic/use-contains.md b/docs/rules/idiomatic/use-contains.md index 304f7c57..e534d2ab 100644 --- a/docs/rules/idiomatic/use-contains.md +++ b/docs/rules/idiomatic/use-contains.md @@ -4,13 +4,12 @@ **Category**: Idiomatic -## Notice: Rule made obsolete by OPA 1.0 +## Notice: Rule disabled by default since OPA 1.0 -Since Regal v0.30.0, this rule is only enabled for projects that have either been explicitly configured to target -versions of OPA before 1.0, or if no configuration is provided — where Regal is able to determine that an older version -of OPA/Rego is being targeted. Consult the documentation on Regal's -[configuration](https://openpolicyagent.org/projects/regal#configuration) for information on how to best work with older versions of -OPA and Rego. +This rule is only enabled for projects that have either been explicitly configured to target versions of OPA before 1.0, +or if no configuration is provided — where Regal is able to determine that an older version of OPA/Rego is being +targeted. Consult the documentation on Regal's [configuration](https://openpolicyagent.org/projects/regal#configuration) +for information on how to best work with older versions of OPA and Rego. Since OPA v1.0, this rule is no longer needed as the Rego v1 syntax is now mandatory, and using `contains` is now the de-facto way to define multi-value rules. diff --git a/docs/rules/idiomatic/use-if.md b/docs/rules/idiomatic/use-if.md index 36f6b173..04107afd 100644 --- a/docs/rules/idiomatic/use-if.md +++ b/docs/rules/idiomatic/use-if.md @@ -4,11 +4,12 @@ **Category**: Idiomatic -## Notice: Rule made obsolete by OPA 1.0 +## Notice: Rule disabled by default since OPA 1.0 -Since Regal v0.30.0, this rule is only enabled for projects explicitly configured to target versions of OPA before 1.0. -Consult the documentation on Regal's [configuration](https://openpolicyagent.org/projects/regal#configuration) for information on how -to best work with older versions of OPA and Rego. +This rule is only enabled for projects that have either been explicitly configured to target versions of OPA before 1.0, +or if no configuration is provided — where Regal is able to determine that an older version of OPA/Rego is being +targeted. Consult the documentation on Regal's [configuration](https://openpolicyagent.org/projects/regal#configuration) +for information on how to best work with older versions of OPA and Rego. Since OPA v1.0, this rule is no longer needed simply because the Rego v1 syntax is made mandatory, and the use of `if` is now enforced before all rule bodies. diff --git a/docs/rules/imports/implicit-future-keywords.md b/docs/rules/imports/implicit-future-keywords.md index 099dd039..f2a9b69f 100644 --- a/docs/rules/imports/implicit-future-keywords.md +++ b/docs/rules/imports/implicit-future-keywords.md @@ -4,6 +4,13 @@ **Category**: Imports +## Notice: Rule disabled by default since OPA 1.0 + +This rule is only enabled for projects that have either been explicitly configured to target versions of OPA before 1.0, +or if no configuration is provided — where Regal is able to determine that an older version of OPA/Rego is being +targeted. Consult the documentation on Regal's [configuration](https://openpolicyagent.org/projects/regal#configuration) +for information on how to best work with older versions of OPA and Rego. + **Avoid** ```rego package policy diff --git a/docs/rules/imports/import-shadows-import.md b/docs/rules/imports/import-shadows-import.md index 57c43484..158639c6 100644 --- a/docs/rules/imports/import-shadows-import.md +++ b/docs/rules/imports/import-shadows-import.md @@ -4,13 +4,12 @@ **Category**: Imports -## Notice: Rule made obsolete by OPA 1.0 +## Notice: Rule disabled by default since OPA 1.0 -Since Regal v0.30.0, this rule is only enabled for projects that have either been explicitly configured to target -versions of OPA before 1.0, or if no configuration is provided — where Regal is able to determine that an older version -of OPA/Rego is being targeted. Consult the documentation on Regal's -[configuration](https://openpolicyagent.org/projects/regal#configuration) for information on how to best work with older versions of -OPA and Rego. +This rule is only enabled for projects that have either been explicitly configured to target versions of OPA before 1.0, +or if no configuration is provided — where Regal is able to determine that an older version of OPA/Rego is being +targeted. Consult the documentation on Regal's [configuration](https://openpolicyagent.org/projects/regal#configuration) +for information on how to best work with older versions of OPA and Rego. Since OPA v1.0, this rule is automatically disabled as OPA itself now forbids this, and shadowed imports will result in a parse error. diff --git a/docs/rules/imports/use-rego-v1.md b/docs/rules/imports/use-rego-v1.md index 4af84009..468946ad 100644 --- a/docs/rules/imports/use-rego-v1.md +++ b/docs/rules/imports/use-rego-v1.md @@ -8,11 +8,10 @@ ## Notice: Rule disabled by default since OPA 1.0 -Since Regal v0.30.0, this rule is only enabled for projects that have either been explicitly configured to target -versions of OPA before 1.0, or if no configuration is provided — where Regal is able to determine that an older version -of OPA/Rego is being targeted. Consult the documentation on Regal's -[configuration](https://openpolicyagent.org/projects/regal#configuration) for information on how to best work with older versions of -OPA and Rego. +This rule is only enabled for projects that have either been explicitly configured to target versions of OPA before 1.0, +or if no configuration is provided — where Regal is able to determine that an older version of OPA/Rego is being +targeted. Consult the documentation on Regal's [configuration](https://openpolicyagent.org/projects/regal#configuration) +for information on how to best work with older versions of OPA and Rego. Since OPA v1.0, the `rego.v1` import is effectively a no-op. Developers working on a **policy library**, or other Rego polices that are expected to be used with many different OPA versions, may however benefit from enabling this rule,