Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Update name of v0-v1 flag #10

Merged
merged 1 commit into from
Dec 18, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 4 additions & 6 deletions docs/content/v0-compatibility.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,8 +27,8 @@ to migrate their Rego to be compatible with OPA v1.0 using the below tooling opt

1. The `rego.v1` import makes OPA apply all restrictions that are enforced by default in OPA v1.0.
If a Rego module imports `rego.v1`, it means applicable `future.keywords` imports are implied. It is illegal to import both `rego.v1` and `future.keywords` in the same module.
2. The `--rego-v1` flag on the `opa fmt` command will rewrite existing modules to use the `rego.v1` import instead of `future.keywords` imports.
3. The `--rego-v1` flag on the `opa check` command will check that either the `rego.v1` import or applicable `future.keywords` imports are present if any of the `in`, `every`, `if` and `contains` keywords are used in a module.
2. The `--v0-v1` flag on the `opa fmt` command will rewrite existing modules to use the `rego.v1` import instead of `future.keywords` imports.
3. The `--v0-v1` flag on the `opa check` command will check that either the `rego.v1` import or applicable `future.keywords` imports are present if any of the `in`, `every`, `if` and `contains` keywords are used in a module.

### v0.x compatibility mode in the OPA binary

Expand All @@ -42,18 +42,16 @@ releases:
- `eval`: supports Rego v0.x syntax modules, use of `import rego.v1` is optional.
- `exec`: supports Rego v0.x syntax modules, use of `import rego.v1` is optional.
- `fmt`*: formats modules to be compatible with OPA v0.x syntax. See note about
`--rego-v1` flag below.
`--v0-v1` flag below.
- `inspect`: supports Rego v0.x syntax modules, use of `import rego.v1` is optional.
- `parse`: supports Rego v0.x syntax modules, use of `import rego.v1` is optional.
- `run`: supports modules (including discovery bundle) using Rego v0.x syntax, use of `import rego.v1` is optional. Binds server listeners to all interfaces by default, rather than localhost.
- `test`: supports Rego v0.x syntax modules, use of `import rego.v1` is optional.

Note (*): the `check` and `fmt` commands also support the `--rego-v1` flag,
Note (*): the `check` and `fmt` commands also support the `--v0-v1` flag,
which will check/format Rego modules as if compatible with the Rego syntax of
_both_ the old 0.x OPA version and current OPA v1.0.

Note (*): the `--rego-v1` flag is not supported before OPA `v0.59.0`.

Note (*): Pre v1.0 versions of OPA also support a comparable `--v1-compatible`
flag which can be used to produce and consume Rego v1 bundles. See
[Upgrading to v1.0](./v0-upgrade) for more information on how to use this flag
Expand Down
10 changes: 6 additions & 4 deletions docs/content/v0-upgrade.md
Original file line number Diff line number Diff line change
Expand Up @@ -455,12 +455,14 @@ upgrade their Rego code to conform to best practices, and to be compatible with
OPA v1.0. These steps are largely based on the process outlined in this
[detailed blog post](https://www.styra.com/blog/renovating-rego/).

1. `opa check`, this will catch any parse or compilation errors.
2. `opa check --strict`, this will raise a number of other issues found in code
Before starting the upgrade, users are recommended to ensure they have a local
OPA binary of version 1.0 or later.

1. `opa check --v0-v1`, this will catch any parse or compilation errors.
2. `opa check --v0-v1 --strict`, this will raise a number of other issues found in code
that might make it incompatible with OPA v1.0 such as the use of deprecated
built-ins or duplicate imports.
3. Automatically reformat your code for OPA v1.0 with
`opa fmt --write --rego-v1`.
3. Automatically reformat your code for OPA v1.0 with `opa fmt --write --v0-v1`.
4. `regal lint`, the [Regal linter](/integrations/regal/) has many more rules to
test for issues in Rego code that can lead to errors, poor performance or
unexpected behaviour.
Expand Down
Loading