From 40b877bab117a833d6aac9767b13376ec679a12a Mon Sep 17 00:00:00 2001 From: Paul Gottschling Date: Tue, 12 Nov 2024 16:11:50 -0500 Subject: [PATCH] Adjust levels of Vale rules Change the error levels of Vale style rules to pave the way for requiring the Vale linter. Use the `warning` level for all rules except for the step numbering rule. This mostly preserves the existing "check prose style" GitHub Actions job behavior, in which Vale style rules are optional. The one rule we require is to ensure that numbered `Step n/d` headings follow the correct numbering scheme. --- docs/vale-styles/3rd-party-products/aws-vs-amazon.yml | 1 - docs/vale-styles/examples/teleport-accounts.yml | 4 ++-- docs/vale-styles/messaging/capitalization.yml | 2 +- docs/vale-styles/messaging/consistent-terms.yml | 2 +- docs/vale-styles/messaging/protocol-products.yml | 2 +- docs/vale-styles/structure/architecture-h2.yml | 2 +- docs/vale-styles/structure/intro-paragraph.yml | 2 +- 7 files changed, 7 insertions(+), 8 deletions(-) diff --git a/docs/vale-styles/3rd-party-products/aws-vs-amazon.yml b/docs/vale-styles/3rd-party-products/aws-vs-amazon.yml index c52b383736a42..ee31641ada6cf 100644 --- a/docs/vale-styles/3rd-party-products/aws-vs-amazon.yml +++ b/docs/vale-styles/3rd-party-products/aws-vs-amazon.yml @@ -15,7 +15,6 @@ # /^AWS /{ print gensub(/AWS (.*)/," \"Amazon \\1\"","1") ": " $0}' extends: substitution message: "Incorrect AWS product name. Use %s instead of %s." -scope: raw level: warning ignorecase: true swap: diff --git a/docs/vale-styles/examples/teleport-accounts.yml b/docs/vale-styles/examples/teleport-accounts.yml index 1b487a3398dee..dd5d49e21136b 100644 --- a/docs/vale-styles/examples/teleport-accounts.yml +++ b/docs/vale-styles/examples/teleport-accounts.yml @@ -1,8 +1,8 @@ extends: substitution message: "Incorrect example of a Teleport account URL. Use %s instead of %s." -level: error +scope: raw # So we can catch instances in code fences +level: warning scope: - - raw ignorecase: true swap: - 'https://(?!status|example)\w+.teleport\.sh': 'example.teleport.sh (or status.teleport.sh for the status page)' diff --git a/docs/vale-styles/messaging/capitalization.yml b/docs/vale-styles/messaging/capitalization.yml index 5e96accb7a5fa..214045a982528 100644 --- a/docs/vale-styles/messaging/capitalization.yml +++ b/docs/vale-styles/messaging/capitalization.yml @@ -5,7 +5,7 @@ scope: - list - paragraph message: "Capitalize the names of Teleport services and features (%s is incorrect). See the Core Concepts page (https://goteleport.com/docs/core-concepts/) for a reference." -level: error +level: warning ignorecase: false tokens: # Allow for mentions of a local proxy service, but not "proxy service". diff --git a/docs/vale-styles/messaging/consistent-terms.yml b/docs/vale-styles/messaging/consistent-terms.yml index 027c0c59f2e18..95aea349b7cd1 100644 --- a/docs/vale-styles/messaging/consistent-terms.yml +++ b/docs/vale-styles/messaging/consistent-terms.yml @@ -7,7 +7,7 @@ scope: - list - paragraph message: For consistent product messaging in the docs, use '%s' instead of '%s'. -level: error +level: warning # Ignoring case because this rule is about word choice, rather than its # presentation/format. ignorecase: true diff --git a/docs/vale-styles/messaging/protocol-products.yml b/docs/vale-styles/messaging/protocol-products.yml index 45a0348f8ade9..2515b2975a3f6 100644 --- a/docs/vale-styles/messaging/protocol-products.yml +++ b/docs/vale-styles/messaging/protocol-products.yml @@ -1,6 +1,6 @@ extends: existence message: Avoid the impression that Teleport consists of multiple products for secure access, e.g., "Database Access" or "Server Access". Instead, talk about enrolling resources in your Teleport cluster, protecting resources with Teleport, or the ability for Teleport to proxy various protocols. -level: error +level: warning ignorecase: false tokens: - 'Server Access' diff --git a/docs/vale-styles/structure/architecture-h2.yml b/docs/vale-styles/structure/architecture-h2.yml index 4889bd4aaf96d..297571def5150 100644 --- a/docs/vale-styles/structure/architecture-h2.yml +++ b/docs/vale-styles/structure/architecture-h2.yml @@ -6,7 +6,7 @@ # This style defines a how-to guide as any guide that includes at least one H2 # beginning "Step [0-9]". extends: script -level: error +level: warning message: "In a how-to guide, the first H2-level section must be called `## How it works`. Use this section to include 1-3 paragraphs that describe the high-level architecture of the setup shown in the guide, i.e., which infrastructure components are involved and how they communicate. If there is already architectural information in the guide, include it in a `## How it works` section." scope: raw script: | diff --git a/docs/vale-styles/structure/intro-paragraph.yml b/docs/vale-styles/structure/intro-paragraph.yml index 3bee6806e4d66..1c34b054b2c2a 100644 --- a/docs/vale-styles/structure/intro-paragraph.yml +++ b/docs/vale-styles/structure/intro-paragraph.yml @@ -1,7 +1,7 @@ # This style enforces the presence of an introductory paragraph before the first # H2 of a docs page. extends: script -level: error +level: warning message: There must be a brief intro paragraph before the first H2-level section of a docs page. Use this to describe the purpose of the guide so a reader can determine whether they should continue reading. If the guide introduces a feature, describe the purpose and benefits of the feature. If there is already an "Introduction" H2 or similar, remove the heading. scope: raw script: |