From 63796702a5ad8fb967b4582d1e7697889b703cf0 Mon Sep 17 00:00:00 2001 From: "Daniel D. Beck" Date: Wed, 11 Jun 2025 14:14:09 +0200 Subject: [PATCH] Add Vale prose linting to feature descriptions --- .github/workflows/pull_request.yml | 8 ++++++++ .vale.ini | 6 ++++++ .vale/config/views/features.yml | 5 +++++ .vale/web-features-styles/Avoid.yml | 6 ++++++ .vale/web-features-styles/Substitute.yml | 9 +++++++++ docs/guidelines.md | 13 +++++++++++++ features/beforeunload.yml | 2 +- features/charset.yml | 2 +- features/del.yml | 2 +- features/font-kerning.yml | 2 +- features/form-associated-custom-elements.yml | 2 +- features/hidden-until-found.yml | 2 +- features/idle-detection.yml | 2 +- features/ins.yml | 2 +- features/optional-catch-binding.yml | 2 +- features/print-events.yml | 2 +- 16 files changed, 57 insertions(+), 10 deletions(-) create mode 100644 .vale.ini create mode 100644 .vale/config/views/features.yml create mode 100644 .vale/web-features-styles/Avoid.yml create mode 100644 .vale/web-features-styles/Substitute.yml diff --git a/.github/workflows/pull_request.yml b/.github/workflows/pull_request.yml index c576605be43..f53cd8ebb30 100644 --- a/.github/workflows/pull_request.yml +++ b/.github/workflows/pull_request.yml @@ -29,6 +29,14 @@ jobs: cache: npm - run: npm ci - run: npm test + vale: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: errata-ai/vale-action@d89dee975228ae261d22c15adcd03578634d429c # v2.1.1 + with: + fail_on_error: true + version: 3.12.0 env: FORCE_COLOR: 3 diff --git a/.vale.ini b/.vale.ini new file mode 100644 index 00000000000..a996888c540 --- /dev/null +++ b/.vale.ini @@ -0,0 +1,6 @@ +StylesPath = .vale + +[features/*.yml] +View = features +BasedOnStyles = Vale, web-features-styles +Vale.Spelling = NO diff --git a/.vale/config/views/features.yml b/.vale/config/views/features.yml new file mode 100644 index 00000000000..56f1634a6e3 --- /dev/null +++ b/.vale/config/views/features.yml @@ -0,0 +1,5 @@ +engine: dasel +scopes: + - name: description + expr: description + type: md diff --git a/.vale/web-features-styles/Avoid.yml b/.vale/web-features-styles/Avoid.yml new file mode 100644 index 00000000000..25abfc98b23 --- /dev/null +++ b/.vale/web-features-styles/Avoid.yml @@ -0,0 +1,6 @@ +extends: existence +message: Consider removing '%s' +level: warning +ignorecase: true +tokens: + - is used to diff --git a/.vale/web-features-styles/Substitute.yml b/.vale/web-features-styles/Substitute.yml new file mode 100644 index 00000000000..7ca0ad84502 --- /dev/null +++ b/.vale/web-features-styles/Substitute.yml @@ -0,0 +1,9 @@ +extends: substitution +message: Consider using '%s' instead of '%s' +level: warning +ignorecase: false +# swap maps tokens in form of bad: good +swap: + defines: sets + specifies: sets + determines: sets diff --git a/docs/guidelines.md b/docs/guidelines.md index 181feb12705..2a1cb12dd34 100644 --- a/docs/guidelines.md +++ b/docs/guidelines.md @@ -79,6 +79,11 @@ The identifier should match the name, with these additional guidelines: ## Descriptions +> [!TIP] +> Some description rules are enforced by linting with Vale. +> A workflow reviews files that you change in your pull request and suggest changes. +> To run the Vale linter locally, [install Vale](https://vale.sh/docs/install) and run `vale .` from the root of the repository. + The `description` field contains a short description of the feature in Markdown-formatted text, which is converted to HTML in the published package. Follow the general writing guidelines in this section, but see the [word and phrase list](#word-and-phrase-list) for specific usage instructions. @@ -158,12 +163,16 @@ Avoid. See [sets](#sets). ([#727](https://github.com/web-platform-dx/web-features/pull/727#discussion_r1537635491)) +⚠️ Warned by vale: [`Substitute.yml`](/.vale/web-features-styles/Substitute.yml) + #### determines Avoid. See [sets](#sets). ([#727](https://github.com/web-platform-dx/web-features/pull/727#discussion_r1537635491)) +⚠️ Warned by vale: [`Substitute.yml`](/.vale/web-features-styles/Substitute.yml) + #### device Use "device" to refer to the underlying operating system or hardware environment, or combination thereof. @@ -195,6 +204,8 @@ Omit "is used" where there's no loss in meaning. For example, prefer "The feature reads…" over "The feature is used to read…" ([#727](https://github.com/web-platform-dx/web-features/pull/727#discussion_r1537635981)) +✅ Required by vale: [`Avoid.yml`](/.vale/web-features-styles/Avoid.yml) + #### longhands and shorthands Use the terms "shorthand" and "longhand" to describe the relationship between CSS properties that combine multiple properties into a single declaration and the individual properties. @@ -231,6 +242,8 @@ Avoid. See [sets](#sets). ([#727](https://github.com/web-platform-dx/web-features/pull/727#discussion_r1537635491)) +⚠️ Warned by vale: [`Substitute.yml`](/.vale/web-features-styles/Substitute.yml) + #### styling … as … by default Use this phrase (or using another appropriate preposition, such as "styling in") to note conventional or standardized default styling. diff --git a/features/beforeunload.yml b/features/beforeunload.yml index 72b6eb8d06c..dd11ac62a33 100644 --- a/features/beforeunload.yml +++ b/features/beforeunload.yml @@ -1,5 +1,5 @@ name: beforeunload -description: "The `beforeunload` event is fired when the current window is about to be unloaded. Typically this is used to display a dialog to confirm if users really want to leave the page when there is unsaved data that would be lost." +description: "The `beforeunload` event is fired when the current window is about to be unloaded. Typically you use this to display a dialog to confirm if users really want to leave the page when there is unsaved data that would be lost." spec: https://html.spec.whatwg.org/multipage/nav-history-apis.html#the-beforeunloadevent-interface status: compute_from: api.Window.beforeunload_event diff --git a/features/charset.yml b/features/charset.yml index a48db148796..41b7bdd9df5 100644 --- a/features/charset.yml +++ b/features/charset.yml @@ -1,5 +1,5 @@ name: "@charset" -description: The `@charset` CSS at-rule specifies the character encoding of an external style sheet. +description: The `@charset` CSS at-rule specifies the character encoding of an external style sheet. spec: https://drafts.csswg.org/css2/#charset group: css compat_features: diff --git a/features/del.yml b/features/del.yml index d82c94542f2..eeea5a65d14 100644 --- a/features/del.yml +++ b/features/del.yml @@ -1,5 +1,5 @@ name: -description: The `` element element represents a range of text that has been deleted from a document, styling text as strikethrough by default. +description: The `` element element represents a range of text that has been deleted from a document, styling text as strikethrough by default. spec: https://html.spec.whatwg.org/multipage/edits.html#the-del-element group: html-elements compat_features: diff --git a/features/font-kerning.yml b/features/font-kerning.yml index 49876d874ad..9ff285ff36b 100644 --- a/features/font-kerning.yml +++ b/features/font-kerning.yml @@ -1,5 +1,5 @@ name: font-kerning -description: The `font-kerning` CSS property sets whether kerning data from a font is used to adjust the space between letters. +description: The `font-kerning` CSS property sets whether to use kerning data from a font to adjust the space between letters. spec: https://drafts.csswg.org/css-fonts-4/#font-kerning-prop group: font-features caniuse: font-kerning diff --git a/features/form-associated-custom-elements.yml b/features/form-associated-custom-elements.yml index c0fb04af6c1..602b1616f09 100644 --- a/features/form-associated-custom-elements.yml +++ b/features/form-associated-custom-elements.yml @@ -1,5 +1,5 @@ name: Form-associated custom elements -description: Custom elements may act like built-in form elements, via the the `attachInternals()` method of `HTMLElement` and the `ElementInternals` API. +description: Custom elements may act like built-in form elements, via the `attachInternals()` method of `HTMLElement` and the `ElementInternals` API. spec: https://html.spec.whatwg.org/multipage/custom-elements.html#form-associated-custom-elements group: - custom-elements diff --git a/features/hidden-until-found.yml b/features/hidden-until-found.yml index 0de66d2d00d..e59de643f4d 100644 --- a/features/hidden-until-found.yml +++ b/features/hidden-until-found.yml @@ -1,5 +1,5 @@ name: hidden="until-found" -description: 'The `hidden="until-found"` attribute hides an element until it is found using the browser''s find-in-page search or it is directly navigated to by following a URL fragment.' +description: The `hidden="until-found"` attribute hides an element until it is found using the browser's find-in-page search or it is directly navigated to by following a URL fragment. spec: https://html.spec.whatwg.org/multipage/interaction.html#attr-hidden-until-found group: html compat_features: diff --git a/features/idle-detection.yml b/features/idle-detection.yml index 58bdd13abf2..61b85d363d1 100644 --- a/features/idle-detection.yml +++ b/features/idle-detection.yml @@ -1,3 +1,3 @@ name: Idle detection -description: The `IdleDetector` API is used to notify a webpage of the user's idle, active, and locked state. +description: The `IdleDetector` API notifies a webpage of the user's idle, active, and locked state. spec: https://wicg.github.io/idle-detection/ diff --git a/features/ins.yml b/features/ins.yml index 4ad11aade85..bac72891d65 100644 --- a/features/ins.yml +++ b/features/ins.yml @@ -1,5 +1,5 @@ name: -description: The `` element element represents a range of text that has been inserted into a document, styling text as underlined by default. +description: The `` element represents a range of text that has been inserted into a document, styling text as underlined by default. spec: https://html.spec.whatwg.org/multipage/edits.html#the-ins-element group: html-elements # TODO - Removed until #1173 is resolved, these APIs are currently listed diff --git a/features/optional-catch-binding.yml b/features/optional-catch-binding.yml index ebdb568c1ff..f797478a2ed 100644 --- a/features/optional-catch-binding.yml +++ b/features/optional-catch-binding.yml @@ -1,5 +1,5 @@ name: Optional catch binding -description: Omit the the binding parameter of a `catch` clause when you don't need information about the exception in a `try ... catch` statement. +description: Omit the binding parameter of a `catch` clause when you don't need information about the exception in a `try ... catch` statement. spec: https://tc39.es/ecma262/multipage/ecmascript-language-statements-and-declarations.html#sec-try-statement group: javascript snapshot: ecmascript-2019 diff --git a/features/print-events.yml b/features/print-events.yml index 7bc9e49638b..c7acad7475b 100644 --- a/features/print-events.yml +++ b/features/print-events.yml @@ -1,5 +1,5 @@ name: Print events -description: An alternative to `@media print` queries, the `beforeprint` and `afterprint` events allow you to change the page for printing and and restore the page after printing. +description: An alternative to `@media print` queries, the `beforeprint` and `afterprint` events allow you to change the page for printing and restore the page after printing. group: print spec: - https://html.spec.whatwg.org/multipage/indices.html#event-afterprint