From a99e5a9aa665e88babc85a5d793418e6bb5189ce Mon Sep 17 00:00:00 2001 From: Stephan Renatus Date: Fri, 29 Jul 2022 17:45:03 +0200 Subject: [PATCH] docs: add warning about importing 'future.keywords' (#4947) While the information may have been there before, it's not been obvious enough. This should change that. Signed-off-by: Stephan Renatus --- docs/content/_index.md | 16 ++++++---------- docs/content/policy-language.md | 26 +++++++++++++++----------- docs/content/policy-reference.md | 2 +- 3 files changed, 22 insertions(+), 22 deletions(-) diff --git a/docs/content/_index.md b/docs/content/_index.md index 91564c3a7d..fec636b71c 100644 --- a/docs/content/_index.md +++ b/docs/content/_index.md @@ -119,12 +119,8 @@ and rules and observe the difference in output. Note that the examples in this section try to represent the best practices. As such, they make use of keywords that are meant to become standard keywords -at some point in time, but have been introduced gradually. These _future -keywords_ can be enabled using - -```live:eg/import:module:read_only -import future.keywords -``` +at some point in time, but have been introduced gradually. +[See the docs on _future keywords_](./policy-language/#future-keywords) for more information. {{< /info >}} ### References @@ -382,7 +378,6 @@ to express _FOR SOME_ and _FOR ALL_ more explicitly. {{< info >}} To ensure backwards-compatibility, the keywords discussed below introduced slowly. In the first stage, users can opt-in to using the new keywords via a special import: -`import future.keywords` introduces _all_ future keywords, and `import future.keywords.every` introduces the `every` keyword described here. (Importing `every` means also importing `in` without an extra `import` statement.) @@ -390,6 +385,7 @@ At some point in the future, the keyword will become _standard_, and the import become a no-op that can safely be removed. This should give all users ample time to update their policies, so that the new keyword will not cause clashes with existing variable names. +[See the docs on _future keywords_](#future-keywords) for more information. {{< /info >}} ##### FOR SOME (`some`) @@ -747,9 +743,9 @@ For example: ```live:example/final:module:openable,merge_down package example -import future.keywords # we want "every" and "in" +import future.keywords.every # "every" implies "in" -allow := true { # allow is true if... +allow := true { # allow is true if... count(violation) == 0 # there are zero violations. } @@ -763,7 +759,7 @@ violation[server.id] { # a server is in the violati "telnet" in server.protocols # it contains the "telnet" protocol. } -public_servers[server] { # a server exists in the public_servers set if... +public_servers[server] { # a server exists in the public_servers set if... some server in input.servers # it exists in the input.servers collection and... some port in server.ports # it references a port in the input.ports collection and... diff --git a/docs/content/policy-language.md b/docs/content/policy-language.md index ef487d0e41..65e32d44b9 100644 --- a/docs/content/policy-language.md +++ b/docs/content/policy-language.md @@ -27,12 +27,8 @@ of the system. {{< info >}} The examples in this section try to represent the best practices. As such, they make use of keywords that are meant to become standard keywords at some point in -time, but have been introduced gradually. These _future keywords_ can be enabled -using - -```live:eg/import:module:read_only -import future.keywords -``` +time, but have been introduced gradually. +[See the docs on _future keywords_](#future-keywords) for more information. {{< /info >}} ## Why use Rego? @@ -1292,6 +1288,16 @@ In the first stage, users can opt-in to using the new keywords via a special imp - `import future.keywords` introduces _all_ future keywords, and - `import future.keyword.x` _only_ introduces the `x` keyword -- see below for all known future keywords. +{{< danger >}} +Using `import future.keywords` to import all future keywords means an **opt-out of a +safety measure**: + +With a new version of OPA, the set of "all" future keywords can grow, and policies that +worked with the previous version of OPA stop working. + +This **cannot happen** when you selectively import the future keywords as you need them. +{{< /danger>}} + At some point in the future, the keyword will become _standard_, and the import will become a no-op that can safely be removed. This should give all users ample time to update their policies, so that the new keyword will not cause clashes with existing @@ -1417,6 +1423,8 @@ For using the `some` keyword with iteration, see `every` is a future keyword and needs to be imported. `import future.keywords.every` introduces the `every` keyword described here. + +[See the docs on _future keywords_](#future-keywords) for more information. {{< /info >}} ```live:eg/data/every0:module:merge_down @@ -1766,13 +1774,9 @@ limit imposed on the number of `else` clauses on a rule. {{< info >}} To ensure backwards-compatibility, new keywords (like `in`) are introduced slowly. In the first stage, users can opt-in to using the new keywords via a special import: -`import future.keywords` introduces _all_ future keywords, and `import future.keywords.in` introduces the `in` keyword described here. -At some point in the future, the keyword will become _standard_, and the import will -become a no-op that can safely be removed. This should give all users ample time to -update their policies, so that the new keyword will not cause clashes with existing -variable names. +[See the docs on _future keywords_](#future-keywords) for more information. {{< /info >}} The membership operator `in` lets you check if an element is part of a collection (array, set, or object). It always evaluates to `true` or `false`: diff --git a/docs/content/policy-reference.md b/docs/content/policy-reference.md index bbe0a1defc..1c882dab7a 100644 --- a/docs/content/policy-reference.md +++ b/docs/content/policy-reference.md @@ -243,7 +243,7 @@ a := 100 if { ... } a_set[x] { ... } a_set[y] { ... } -# alternatively, with future.keywords +# alternatively, with future.keywords.contains and future.keywords.if a_set contains x if { ... } a_set contains y if { ... }