docs: Add we/our/us check to spell check (#8787)

Signed-off-by: Charlie Egan <charlie_egan@apple.com>
2026-08-12 19:32:48 -06:00 · 2026-06-16 11:32:55 +01:00
parent 7b004efe4a
commit e7d0c0e3d1
18 changed files with 39 additions and 24 deletions
@@ -638,8 +638,7 @@ jobs:
        vale --version

    - name: Run Vale spell check
-      run: vale --config=.vale.ini .
-      working-directory: docs
+      run: make docs-spell-check

  benchmarks:
    name: Benchmarks
@@ -4,10 +4,13 @@ MinAlertLevel = suggestion
 Vocab = Vale

 [*.md]
-BasedOnStyles = Vale
+BasedOnStyles = Vale, OPA
 Vale.Terms = NO
 BlockIgnores = (?s)(```.*?```)

+[build/**]
+BasedOnStyles =
+
 [src/data/ecosystem/entries/*.md]
 Vale.Spelling = NO

@@ -0,0 +1,10 @@
+extends: existence
+message: "Avoid first-person plural '%s'. Use direct address, active before passive."
+level: error
+ignorecase: false
+# Prefix excludes hyphen-prefixed matches (e.g. en-us in frontmatter URLs).
+nonword: true
+tokens:
+  - '(?:^|[^-\w])[Ww]e\b'
+  - '(?:^|[^-\w])[Oo]ur\b'
+  - '(?:^|[^-\w])[Uu]s\b'
@@ -128,3 +128,4 @@ colocating
 datasources
 OCP's
 subnets
+bool
@@ -25,10 +25,10 @@ There are two version tracks for the OPA project:
 2. Stable (vX.Y.Z)

 A new version of OPA is scheduled to release on the last Friday of every month. At the beginning of that week,
-we will create a release candidate branch (`release-<major>.<minor>-rc.0`) from the main branch and create a release
-candidate tag (`v<major>.<minor>.0-rc.0`) based on the release candidate branch for pre-release. Once the pre-release
+a release candidate branch (`release-<major>.<minor>-rc.0`) will be created from the main branch and a release
+candidate tag (`v<major>.<minor>.0-rc.0`) will be created based on the release candidate branch for pre-release. Once the pre-release
 is published, users are encouraged to try out the features, bug fixes in the release candidate. If regressions or bugs
-are detected, they need to get fixed before cutting the stable release. We do not recommend using OPA release
+are detected, they need to get fixed before cutting the stable release. It is not recommended to use OPA release
 candidates in a production environment. The stable release that comes out after the release candidate may be identical
 to the release candidate if no other features or bug fixes are introduced to the main branch in between.

@@ -18,7 +18,7 @@ the [OPA AWS CloudFormation Hook](https://github.com/StyraOSS/opa-aws-cloudforma
 ## Goals

 This tutorial shows how to deploy an AWS CloudFormation Hook that forwards requests to OPA for policy decisions,
-allowing us to use policy to determine whether a request to create, update or delete a resource should be
+allowing policy to determine whether a request to create, update or delete a resource should be
 allowed or denied. This tutorial covers authoring policies that take the input structure of CloudFormation Templates into
 account, and some special considerations to be aware of in this environment.

@@ -29,7 +29,7 @@ When contributing please consider the following pointers:
  OPA users (e.g., vendoring conflicts, security, debugging, etc.)
 - **AI Tooling**: You can use generative AI tooling to assist your work on OPA,
  but please review the project's [AI Guidelines](#ai-guidelines) below before doing so to
-  help us help you.
+  help maintainers help you.

 :::tip
 Looking for developer environment set-up? Head over to the
@@ -4,7 +4,7 @@ title: Docker

 Docker’s out-of-the-box authorization model is all or nothing. But many users
 require finer-grained access control and Docker’s plugin infrastructure allows
-us to do so.
+for this.

 This is an excellent opportunity to see how to policy enable an existing
 service.
@@ -20,7 +20,7 @@ evaluation, policy coverage, and more.
 | TextMate           | [github.com/open-policy-agent/opa/tree/main/misc/syntax/textmate](https://github.com/open-policy-agent/opa/tree/main/misc/syntax/textmate)                                                                                                                                                                                                   |                                            |

 :::info
-**Your editor missing? Built a Rego integration for your editor?** Drop us a
+**Your editor missing? Built a Rego integration for your editor?** Send a
 message on [Slack](https://slack.openpolicyagent.org)
 The [Ecosystem page](/ecosystem/) is also a great place to
 showcase your project. See
@@ -5,7 +5,7 @@ sidebar_position: 6

 This page provides some pointers that could assist in addressing issues encountered while using the
 OPA-Envoy plugin. If none of these tips work, feel free to join
-[our Slack](https://slack.openpolicyagent.org) and ask for help.
+[the OPA Slack](https://slack.openpolicyagent.org) and ask for help.

 ## Debugging Performance Issues

@@ -12,7 +12,7 @@ This tutorial shows how Istio's AuthorizationPolicy can be configured to delegat
 ## Prerequisites

 This tutorial requires Kubernetes 1.20 or later. To run the tutorial locally ensure you start a cluster with Kubernetes
-version 1.20+, we recommend using [minikube](https://kubernetes.io/docs/setup/) or
+version 1.20+, for example [minikube](https://kubernetes.io/docs/setup/) or
 [KIND](https://kind.sigs.k8s.io/).

 The tutorial also requires Istio v1.19.0 or later. It assumes you have Istio deployed on top of Kubernetes.
@@ -5,7 +5,7 @@ title: Debugging Tips
 If you run into problems getting OPA to enforce admission control policies in
 Kubernetes there are a few things you can check to make sure everything is
 configured correctly. If none of these tips work, feel free to join
-[our Slack](https://slack.openpolicyagent.org) and ask for help.
+[the OPA Slack](https://slack.openpolicyagent.org) and ask for help.

 The tips below cover the OPA-Kubernetes integration that uses kube-mgmt.
 The [OPA Gatekeeper version](https://open-policy-agent.github.io/gatekeeper/)
@@ -5,7 +5,7 @@ title: "Tutorial: Ingress Validation"
 This tutorial shows how to deploy OPA as an admission controller from scratch.
 It covers the OPA-Kubernetes version that uses kube-mgmt.
 The [OPA Gatekeeper version](https://open-policy-agent.github.io/gatekeeper) has its own docs.
-For the purpose of the tutorial we will deploy two policies that ensure:
+For the purpose of the tutorial, two policies will be deployed that ensure:

 - Ingress hostnames must be on `allowlist` on the Namespace containing the Ingress.
 - Two ingresses in different namespaces must not have the same hostname.
@@ -18,7 +18,7 @@ the other. This means that it's not possible to enforce these policies during
 admission control 100% of the time. There will be a small window of time
 (usually on the order of milliseconds) when the eventually consistent cache
 inside of OPA (or any other admission controller) is out-of-date. To catch
-these violations we recommend you periodically audit the state of the cluster
+these violations it is recommended to periodically audit the state of the cluster
 against your policies. Offline auditing is one of the features provided by the
 [OPA Gatekeeper](https://github.com/open-policy-agent/gatekeeper) project.
 :::
@@ -26,7 +26,7 @@ against your policies. Offline auditing is one of the features provided by the
 ## Prerequisites

 This tutorial requires Kubernetes 1.20 or later. To run the tutorial locally ensure you start a cluster with Kubernetes
-version 1.20+, we recommend using [minikube](https://kubernetes.io/docs/setup/) or
+version 1.20+, for example [minikube](https://kubernetes.io/docs/setup/) or
 [KIND](https://kind.sigs.k8s.io/).

 ## Steps
@@ -15,7 +15,7 @@ operational aspects.
 - **Deployment Environment:**
  - Running the OCP server within Kubernetes
 - **Database Integration:**
-  - Connecting the OCP server to an external database. For this example, we will set up a PostgreSQL database within the Kubernetes environment, but a more likely solution would be a managed SQL database.
+  - Connecting the OCP server to an external database. For this example, a PostgreSQL database is set up within the Kubernetes environment, but a more likely solution would be a managed SQL database.
 - **Source control integration**:
  - This example will utilize git as the source of the policies
 - **Advanced Bundle Management:**
@@ -37,9 +37,9 @@ The rest of this section will just highlight portions of the full manifests to e

 ## Database Integration

-As mentioned we will use a PostgreSQL deployment/service for this example, but for a production install you will likely want to use an external/managed database. Example configuration can be found in the [Database Configuration](./configuration.md#database-configuration) section.
+As mentioned, this example uses a PostgreSQL deployment/service, but for a production install you will likely want to use an external/managed database. Example configuration can be found in the [Database Configuration](./configuration.md#database-configuration) section.

-The configuration to connect to the database will be in a configuration file. In our example it will look like this:
+The configuration to connect to the database will be in a configuration file. In this example it will look like this:

 ```yaml
 database:
@@ -37,4 +37,4 @@ docs_features:
      OPA. See docs [here](https://docs.envzero.com/guides/integrations/plugins/opa-plugin).
 ---

-env0 is the best way to deploy and manage IaC - Terraform, OpenTofu, CloudFormation, Pulumi, Kubernetes, and more. Our platform integrates with OPA to allow its users to streamline cloud governance, automate policy enforcement, and maintain control over cloud deployments while enabling managed self-service.
+env0 is the best way to deploy and manage IaC - Terraform, OpenTofu, CloudFormation, Pulumi, Kubernetes, and more. The env0 platform integrates with OPA to allow its users to streamline cloud governance, automate policy enforcement, and maintain control over cloud deployments while enabling managed self-service.
@@ -11,4 +11,4 @@ code:
 - https://github.com/microsoft/rego-cpp
 ---

-The rego-cpp project is a Rego compiler and runtime implemented in cross-platform C++. As such, it provides the ability to integrate Rego natively into a wider range of languages on most platforms. In addition to CMake FetchContent support for C and C++, we also distribute a Rust crate and a Python wheel. We regularly update the integration so as to support Rego as of the latest OPA release.
+The rego-cpp project is a Rego compiler and runtime implemented in cross-platform C++. As such, it provides the ability to integrate Rego natively into a wider range of languages on most platforms. In addition to CMake FetchContent support for C and C++, the project also distributes a Rust crate and a Python wheel. The integration is regularly updated to support Rego as of the latest OPA release.
@@ -1,6 +1,8 @@
 ---
-title: C#
+title: "C#"
 website: "https://learn.microsoft.com/en-us/dotnet/csharp/"
 ---

-C# (C-Sharp) is a modern, object-oriented programming language developed by Microsoft. It is widely used for building Windows applications, web services, and enterprise software with the .NET platform.
+C# (C-Sharp) is a modern, object-oriented programming language developed by
+Microsoft. It is widely used for building Windows applications, web services,
+and enterprise software with the .NET platform.
@@ -1,7 +1,7 @@
 # external-resources

 This folder contains a number of resources that are referenced elsewhere on the
-internet in locations we do not control.
+internet in locations outside of this project's control.

 When adding a file here, please make sure to add a redirect in the `_redirects`
 file to ensure that the file is accessible at the same URL as it was before.