From 297cf7a10e5c6eef18d8b58ccb87806d53462d95 Mon Sep 17 00:00:00 2001
From: Charlie Egan <charlie@styra.com>
Date: Tue, 17 Dec 2024 13:48:24 +0000
Subject: [PATCH] docs: Add v0 import example to v0-compatibility

This shows another way to use two versions of rego in the same app.

Signed-off-by: Charlie Egan <charlie@styra.com>
---
 docs/content/v0-compatibility.md | 65 +++++++++++++++++++++++++++++---
 1 file changed, 59 insertions(+), 6 deletions(-)

diff --git a/docs/content/v0-compatibility.md b/docs/content/v0-compatibility.md
index 14535f451eb..ea48888171f 100644
--- a/docs/content/v0-compatibility.md
+++ b/docs/content/v0-compatibility.md
@@ -61,17 +61,19 @@ as part of an upgrade to OPA v1.0.
 
 ### v0.x compatibility mode in Rego package
 
-There are three ways to enable v0.x compatibility mode in the [Rego package](https://pkg.go.dev/github.com/open-policy-agent/opa/rego):
+There are various ways to use v0.x compatible functionality in the
+[Rego package](https://pkg.go.dev/github.com/open-policy-agent/opa/v1/rego):
 
 1. Set the Rego version on modules
 2. Set the Rego version on bundle manifests
 3. Use the SetRegoVersion Rego argument
+4. Import the [v0 package](https://pkg.go.dev/github.com/open-policy-agent/opa/rego)
 
 1 & 2 are preferred as they are more granular and make it easier to run a
 mix of v0.x and v1.0 compatible Rego in the same OPA instance and thus better
 support a gradual upgrade path.
 
-The `SetRegoVersion` method on [Module](https://pkg.go.dev/github.com/open-policy-agent/opa/ast#Module.SetRegoVersion?)
+The `SetRegoVersion` method on [Module](https://pkg.go.dev/github.com/open-policy-agent/opa/v1/ast#Module.SetRegoVersion?)
 can be used like this:
 
 ```go
@@ -82,7 +84,7 @@ m := ast.Module{
 m.SetRegoVersion(ast.RegoV0)
 ```
 
-Similarly, the [Bundle Manifest](https://pkg.go.dev/github.com/open-policy-agent/opa/bundle#Manifest.SetRegoVersion) Rego version
+Similarly, the [Bundle Manifest](https://pkg.go.dev/github.com/open-policy-agent/opa/v1/bundle#Manifest.SetRegoVersion) Rego version
 can be set like this:
 
 ```go
@@ -92,9 +94,10 @@ b := Bundle{
 b.SetRegoVersion(ast.RegoV0)
 ```
 
-If you cannot set the Rego version on modules or bundle manifests, you
-can use the [`SetRegoVersion`](https://pkg.go.dev/github.com/open-policy-agent/opa/rego#SetRegoVersion) Rego argument to control the Rego version used when
-evaluating policies.
+If you cannot set the Rego version on modules or bundle manifests, you can use
+the
+[`SetRegoVersion`](https://pkg.go.dev/github.com/open-policy-agent/opa/v1/rego#SetRegoVersion)
+Rego argument to control the Rego version used when evaluating policies.
 
 Users are encouraged to use the more granular options where possible to better
 allow them to upgrade Rego used in their system to Rego v1 gradually.
@@ -111,6 +114,56 @@ r := rego.New(
 )
 ```
 
+Finally, another option is to import the `v0` package instead. This can even be
+used alongside the `v1` package in the same program if required. The program
+below will evaluate the same Rego using both the v0 and v1 Rego packages, v1 is
+running in v0 compatibility mode with `SetRegoVersion`:
+
+```go
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+
+	v0rego "github.com/open-policy-agent/opa/rego"
+	v1ast "github.com/open-policy-agent/opa/v1/ast"
+	v1rego "github.com/open-policy-agent/opa/v1/rego"
+)
+
+func main() {
+	// we have a v0 Rego module, we want to evaluate it using the v1 rego
+	// package and the v0 rego package in the same program.
+	module := `package example
+
+messages[msg] {
+	msg := "foo"
+}
+`
+
+	rv1 := v1rego.New(
+		v1rego.Query("data.example.messages"),
+		v1rego.SetRegoVersion(v1ast.RegoV0),
+		v1rego.Module("example.rego", module),
+	)
+
+	rs, _ := rv1.Eval(context.TODO())
+	bs, _ := json.Marshal(rs)
+	fmt.Println(string(bs))
+
+	rv0 := v0rego.New(
+		v0rego.Query("data.example.messages"),
+		v0rego.Module("example.rego", module),
+	)
+
+	rs, _ = rv0.Eval(context.TODO())
+	bs, _ = json.Marshal(rs)
+
+	fmt.Println(string(bs))
+}
+```
+
 ### v0.x compatibility mode in the OPA Go SDK
 
 {{< info >}}