diff --git a/.github/workflows/pull-request.yaml b/.github/workflows/pull-request.yaml index b21fc435b8..e6f80e01d0 100644 --- a/.github/workflows/pull-request.yaml +++ b/.github/workflows/pull-request.yaml @@ -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 diff --git a/docs/.vale.ini b/docs/.vale.ini index cb41bb43d9..c88fc30dcb 100644 --- a/docs/.vale.ini +++ b/docs/.vale.ini @@ -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 diff --git a/docs/config/OPA/WeOur.yml b/docs/config/OPA/WeOur.yml new file mode 100644 index 0000000000..4dca54348a --- /dev/null +++ b/docs/config/OPA/WeOur.yml @@ -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' diff --git a/docs/config/config/vocabularies/Vale/accept.txt b/docs/config/config/vocabularies/Vale/accept.txt index b0e1477113..58880e0424 100644 --- a/docs/config/config/vocabularies/Vale/accept.txt +++ b/docs/config/config/vocabularies/Vale/accept.txt @@ -128,3 +128,4 @@ colocating datasources OCP's subnets +bool diff --git a/docs/devel/RELEASE.md b/docs/devel/RELEASE.md index 5b2c115744..fe88ea4b8e 100644 --- a/docs/devel/RELEASE.md +++ b/docs/devel/RELEASE.md @@ -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-.-rc.0`) from the main branch and create a release -candidate tag (`v..0-rc.0`) based on the release candidate branch for pre-release. Once the pre-release +a release candidate branch (`release-.-rc.0`) will be created from the main branch and a release +candidate tag (`v..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. diff --git a/docs/docs/aws-cloudformation-hooks.md b/docs/docs/aws-cloudformation-hooks.md index c4cf67b016..71b52c1a2d 100644 --- a/docs/docs/aws-cloudformation-hooks.md +++ b/docs/docs/aws-cloudformation-hooks.md @@ -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. diff --git a/docs/docs/contrib-code.md b/docs/docs/contrib-code.md index 50ea8e024c..0b881eed05 100644 --- a/docs/docs/contrib-code.md +++ b/docs/docs/contrib-code.md @@ -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 diff --git a/docs/docs/docker-authorization.md b/docs/docs/docker-authorization.md index 85bcf86f8d..82b207731d 100644 --- a/docs/docs/docker-authorization.md +++ b/docs/docs/docker-authorization.md @@ -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. diff --git a/docs/docs/editor-and-ide-support.md b/docs/docs/editor-and-ide-support.md index 4107126e0a..b4d1f8040e 100644 --- a/docs/docs/editor-and-ide-support.md +++ b/docs/docs/editor-and-ide-support.md @@ -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 diff --git a/docs/docs/envoy/debugging.md b/docs/docs/envoy/debugging.md index ec2689c044..1e93914ad3 100644 --- a/docs/docs/envoy/debugging.md +++ b/docs/docs/envoy/debugging.md @@ -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 diff --git a/docs/docs/envoy/tutorial-istio.md b/docs/docs/envoy/tutorial-istio.md index f45925a5e2..55b344d135 100644 --- a/docs/docs/envoy/tutorial-istio.md +++ b/docs/docs/envoy/tutorial-istio.md @@ -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. diff --git a/docs/docs/kubernetes/debugging.md b/docs/docs/kubernetes/debugging.md index d343fcfac5..c2a0378e4c 100644 --- a/docs/docs/kubernetes/debugging.md +++ b/docs/docs/kubernetes/debugging.md @@ -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/) diff --git a/docs/docs/kubernetes/tutorial.md b/docs/docs/kubernetes/tutorial.md index 98c9d60ccb..2c961b248f 100644 --- a/docs/docs/kubernetes/tutorial.md +++ b/docs/docs/kubernetes/tutorial.md @@ -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 diff --git a/docs/docs/ocp/guide-deploy-as-a-service.md b/docs/docs/ocp/guide-deploy-as-a-service.md index 6ec005b349..5d4831f1b4 100644 --- a/docs/docs/ocp/guide-deploy-as-a-service.md +++ b/docs/docs/ocp/guide-deploy-as-a-service.md @@ -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: diff --git a/docs/src/data/ecosystem/entries/env0.md b/docs/src/data/ecosystem/entries/env0.md index 0e17f1acfb..ef739a983e 100644 --- a/docs/src/data/ecosystem/entries/env0.md +++ b/docs/src/data/ecosystem/entries/env0.md @@ -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. diff --git a/docs/src/data/ecosystem/entries/regocpp.md b/docs/src/data/ecosystem/entries/regocpp.md index 994553e28b..26c5a990da 100644 --- a/docs/src/data/ecosystem/entries/regocpp.md +++ b/docs/src/data/ecosystem/entries/regocpp.md @@ -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. diff --git a/docs/src/data/ecosystem/languages/csharp.md b/docs/src/data/ecosystem/languages/csharp.md index a1e26b2354..a30639ec89 100644 --- a/docs/src/data/ecosystem/languages/csharp.md +++ b/docs/src/data/ecosystem/languages/csharp.md @@ -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. diff --git a/docs/static/external-resources/README.md b/docs/static/external-resources/README.md index 0ef4cbd979..9f6cfd4845 100644 --- a/docs/static/external-resources/README.md +++ b/docs/static/external-resources/README.md @@ -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.