Refactor Grafana Vale style so it can be easily packaged

.github/workflows/validate-documentation.yml

@@ -73,11 +73,19 @@ jobs:
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
+      - name: Sync packages
+        run: vale sync
       - name: Run linter
         run: >
-          /bin/reviewdog
-          --conf=/etc/vale/.reviewdog.yml
+          vale
+          '--glob=*.md'
+          --minAlertLevel=warning
+          --output=/etc/vale/rdjsonl.tmpl
+          docs/sources
+          | reviewdog
+          -f=rdjsonl
           --fail-on-error
+          --name=vale
           --reporter=github-pr-review
         env:
           REVIEWDOG_GITHUB_API_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -5,4 +5,5 @@
 /add-to-docs-project/node_modules/
 /add-to-docs-project/index.mjs
 build.conf
-/dist
+/dist
+/vale/Grafana.zip

.vale.ini

@@ -1,6 +1,4 @@
 MinAlertLevel = suggestion
-Packages = Google, https://github.com/errata-ai/Hugo/releases/download/v0.2.0/Hugo.zip, Readability
-StylesPath = vale
+Packages = Google, https://github.com/errata-ai/Hugo/releases/download/v0.2.0/Hugo.zip, Readability, vale/Grafana
 [*]
 BasedOnStyles = Grafana
-TokenIgnores = (<http[^\n]+>+?), \*\*[^\n]+\*\*

RELEASE.md

@@ -0,0 +1,63 @@
+# Releases
+
+The Writers' Toolkit repository is a collection of different tools that can have different release mechanisms.
+
+## GitHub Actions
+
+The following directories contain GitHub Actions actions:
+
+- [`add-to-docs-project`](./add-to-docs-project/)
+- [`prettier`](./prettier/)
+- [`publish-technical-documentation`](./publish-technical-documentation/)
+- [`publish-technical-documentation-release`](./publish-technical-documentation-release/)
+
+You release each action by creating or updating Git tags.
+The Git tag is begins with the action directory followed by a slash (`/`) and then the tag version.
+For example, `publish-technical-documentation-release/v1.0.0` is the v1.0.0 release of the `publish-technical-documentation-release` action.
+
+The actions follow [semantic versioning](https://semver.org/).
+
+To create a tag, use the following command:
+
+```console
+git tag --annotate --force --sign --local-user=<GPG KEY ID> -m <MESSAGE> <TAG>
+```
+
+Where:
+
+- _`<GPG KEY ID>`_ is the ID of the GPG key associated with your GitHub account.
+
+  For more information refer to [Signing commits](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits).
+
+- _`<MESSAGE>`_ is a short message explaining the change to the action.
+
+  This is typically similar to a commit title explaining the "what" of the change.
+
+- _`TAG`_ is the name of the tag using the previously explained naming convention.
+
+Each release has three tags:
+
+- Major version: `<ACTION>/v<MAJOR>`
+- Major and minor version: `<ACTION>/v<MAJOR>.<MINOR>`
+- Major, minor, and patch version: `<ACTION>/v<MAJOR>.<MINOR>.<PATCH>`
+
+The major version tag should point to the same commit as the latest major and minor version tag.
+The major and minor version tag should point to the same commit as the major, minor, and patch version tag.
+
+The `--force` flag provided to the `git tag` command overwrites existing tags which you need to be able to move the major version and major and minor version tags when you release a new major, minor, and patch version.
+
+## Vale package
+
+To release a new version of the Writers' Toolkit Vale package:
+
+1. Create a new tag for the release with the form `vale/<VERSION>`.
+
+   The Vale package follow [semantic versioning](https://semver.org).
+
+1. Using the checked out tag, create an archive of the [Vale package directory](./vale/Grafana).
+
+   ```console
+   cd vale && make Grafana.zip
+   ```
+
+1. Create a GitHub release and upload the [`vale/Grafana.zip`](./vale/Grafana.zip) archive.

docs/make-docs

@@ -6,6 +6,14 @@
 # [Semantic versioning](https://semver.org/) is used to help the reader identify the significance of changes.
 # Changes are relevant to this script and the support docs.mk GNU Make interface.
 #
+# ## 8.2.0 (2024-11-22)
+#
+# ### Added
+#
+# - Debug output of the final command when DEBUG=true.
+#
+#   Useful to inspect if the script is correctly constructing the final command.
+#
 # ## 8.1.0 (2024-08-22)
 #
 # ### Added
@@ -631,7 +639,7 @@ POSIX_HERESTRING
 
     case "${_project}" in
       # Workaround for arbitrary mounts where the version field is expected to be the local directory
-      # and the repo field is expected to be the container directory.
+     # and the repo field is expected to be the container directory.
       arbitrary)
         echo "${_project}^${_version}^${_repo}^" # TODO
         ;;
@@ -801,6 +809,10 @@ case "${image}" in
                 | sed "s#$(proj_dst "${proj}")#sources#"
 EOF
 
+    if [ -n "${DEBUG}" ]; then
+      debg "${cmd}"
+    fi
+
     case "${OUTPUT_FORMAT}" in
       human)
         if ! command -v jq >/dev/null 2>&1; then
@@ -837,6 +849,10 @@ EOF
                 /hugo/content/docs
 EOF
 
+    if [ -n "${DEBUG}" ]; then
+      debg "${cmd}"
+    fi
+
     case "${OUTPUT_FORMAT}" in
       human)
         ${cmd} --output=line \

docs/sources/_index.md

@@ -39,3 +39,6 @@ If it's your first time using the guide, start with the [Get started](https://gr
 
 Writers' Toolkit is open source and available at [`grafana/writers-toolkit`](https://github.com/grafana/writers-toolkit).
 If you have questions, or feedback on how to improve this documentation, [open an issue](https://github.com/grafana/writers-toolkit/issues/new) and help make this an even better resource.
+blah
+blahlskadjflasjdflkasjdf
+blah

docs/sources/review/lint-prose/rules.md

@@ -2,7 +2,7 @@
 date: "2024-06-25"
 description: A description of every Grafana Labs prose linting rule.
 menuTitle: Rules
-review_date: "2024-09-19"
+review_date: "2024-12-05"
 title: Vale rules
 ---
 
@@ -102,8 +102,8 @@ Use 'AM' or 'PM' (preceded by a space).
 
 _`<CURRENT TEXT>`_ was matched by one or more of the following regular expressions:
 
-- `\d{1,2}[AP]M`
-- `\d{1,2} ?[ap]m`
+- `\d{1,2}[AP]M\b`
+- `\d{1,2} ?[ap]m\b`
 - `\d{1,2} ?[aApP]\.[mM]\.`
 
 [More information ->](https://developers.google.com/style/word-list)
@@ -165,47 +165,43 @@ Extends: substitution
 
 Consider using _`<REPLACEMENT TEXT>`_ instead of _`<CURRENT TEXT>`_.
 
-| Current text                   | Replacement text              |
-| ------------------------------ | ----------------------------- |
-| `(?:alumnae\|alumni)`          | `graduates`                   |
-| `(?:alumna\|alumnus)`          | `graduate`                    |
-| `air(?:m[ae]n\|wom[ae]n)`      | `pilot(s)`                    |
-| `anchor(?:m[ae]n\|wom[ae]n)`   | `anchor(s)`                   |
-| `authoress`                    | `author`                      |
-| `camera(?:m[ae]n\|wom[ae]n)`   | `camera operator(s)`          |
-| `chair(?:m[ae]n\|wom[ae]n)`    | `chair(s)`                    |
-| `congress(?:m[ae]n\|wom[ae]n)` | `member(s) of congress`       |
-| `door(?:m[ae]\|wom[ae]n)`      | `concierge(s)`                |
-| `draft(?:m[ae]n\|wom[ae]n)`    | `drafter(s)`                  |
-| `fire(?:m[ae]n\|wom[ae]n)`     | `firefighter(s)`              |
-| `fisher(?:m[ae]n\|wom[ae]n)`   | `fisher(s)`                   |
-| `fresh(?:m[ae]n\|wom[ae]n)`    | `first-year student(s)`       |
-| `garbage(?:m[ae]n\|wom[ae]n)`  | `waste collector(s)`          |
-| `lady lawyer`                  | `lawyer`                      |
-| `ladylike`                     | `courteous`                   |
-| `landlord`                     | `building manager`            |
-| `mail(?:m[ae]n\|wom[ae]n)`     | `mail carriers`               |
-| `man and wife`                 | `husband and wife`            |
-| `man enough`                   | `strong enough`               |
-| `mankind`                      | `human kind`                  |
-| `manmade`                      | `manufactured`                |
-| `manpower`                     | `personnel`                   |
-| `men and girls`                | `men and women`               |
-| `middle(?:m[ae]n\|wom[ae]n)`   | `intermediary`                |
-| `news(?:m[ae]n\|wom[ae]n)`     | `journalist(s)`               |
-| `ombuds(?:man\|woman)`         | `ombuds`                      |
-| `oneupmanship`                 | `upstaging`                   |
-| `poetess`                      | `poet`                        |
-| `police(?:m[ae]n\|wom[ae]n)`   | `police officer(s)`           |
-| `repair(?:m[ae]n\|wom[ae]n)`   | `technician(s)`               |
-| `sales(?:m[ae]n\|wom[ae]n)`    | `salesperson or sales people` |
-| `service(?:m[ae]n\|wom[ae]n)`  | `soldier(s)`                  |
-| `steward(?:ess)?`              | `flight attendant`            |
-| `tribes(?:m[ae]n\|wom[ae]n)`   | `tribe member(s)`             |
-| `waitress`                     | `waiter`                      |
-| `woman doctor`                 | `doctor`                      |
-| `woman scientist[s]?`          | `scientist(s)`                |
-| `work(?:m[ae]n\|wom[ae]n)`     | `worker(s)`                   |
+| Current text                  | Replacement text              |
+| ----------------------------- | ----------------------------- |
+| `(?:alumnae\|alumni)`         | `graduates`                   |
+| `(?:alumna\|alumnus)`         | `graduate`                    |
+| `air(?:m[ae]n\|wom[ae]n)`     | `pilot(s)`                    |
+| `anchor(?:m[ae]n\|wom[ae]n)`  | `anchor(s)`                   |
+| `authoress`                   | `author`                      |
+| `camera(?:m[ae]n\|wom[ae]n)`  | `camera operator(s)`          |
+| `door(?:m[ae]\|wom[ae]n)`     | `concierge(s)`                |
+| `draft(?:m[ae]n\|wom[ae]n)`   | `drafter(s)`                  |
+| `fire(?:m[ae]n\|wom[ae]n)`    | `firefighter(s)`              |
+| `fisher(?:m[ae]n\|wom[ae]n)`  | `fisher(s)`                   |
+| `fresh(?:m[ae]n\|wom[ae]n)`   | `first-year student(s)`       |
+| `garbage(?:m[ae]n\|wom[ae]n)` | `waste collector(s)`          |
+| `lady lawyer`                 | `lawyer`                      |
+| `ladylike`                    | `courteous`                   |
+| `mail(?:m[ae]n\|wom[ae]n)`    | `mail carriers`               |
+| `man and wife`                | `husband and wife`            |
+| `man enough`                  | `strong enough`               |
+| `mankind`                     | `human kind\|humanity`        |
+| `manmade`                     | `manufactured`                |
+| `manpower`                    | `personnel`                   |
+| `middle(?:m[ae]n\|wom[ae]n)`  | `intermediary`                |
+| `news(?:m[ae]n\|wom[ae]n)`    | `journalist(s)`               |
+| `ombuds(?:man\|woman)`        | `ombuds`                      |
+| `oneupmanship`                | `upstaging`                   |
+| `poetess`                     | `poet`                        |
+| `police(?:m[ae]n\|wom[ae]n)`  | `police officer(s)`           |
+| `repair(?:m[ae]n\|wom[ae]n)`  | `technician(s)`               |
+| `sales(?:m[ae]n\|wom[ae]n)`   | `salesperson or sales people` |
+| `service(?:m[ae]n\|wom[ae]n)` | `soldier(s)`                  |
+| `steward(?:ess)?`             | `flight attendant`            |
+| `tribes(?:m[ae]n\|wom[ae]n)`  | `tribe member(s)`             |
+| `waitress`                    | `waiter`                      |
+| `woman doctor`                | `doctor`                      |
+| `woman scientist[s]?`         | `scientist(s)`                |
+| `work(?:m[ae]n\|wom[ae]n)`    | `worker(s)`                   |
 
 [More information ->](https://developers.google.com/style/inclusive-documentation)
 
@@ -217,7 +213,7 @@ _`<CURRENT TEXT>`_ doesn't need a hyphen.
 
 _`<CURRENT TEXT>`_ was matched by one or more of the following regular expressions:
 
-- `\s[^\s-]+ly-`
+- `\b[^\s-]+ly-\w+\b`
 
 [More information ->](https://developers.google.com/style/hyphens)
 
@@ -666,7 +662,7 @@ Extends: capitalization
 
 Use sentence-style capitalization for _`<CURRENT TEXT>`_.
 
-If your heading contains capitalized words that represent product names, you need to add those words as exceptions in https://github.com/grafana/writers-toolkit/blob/main/vale/Grafana/Headings.yml for them to be considered correctly cased.
+If your heading contains capitalized words that represent product names, you need to add those words as exceptions in https://github.com/grafana/writers-toolkit/blob/main/vale/Grafana/styles/GrafanaHeadings.yml for them to be considered correctly cased.
 
 Vale considers multi-word exceptions such as _Grafana Enterprise Metrics_ as a single correctly cased word.
 

publish-technical-documentation-release/action.yaml

@@ -102,6 +102,25 @@ runs:
       with:
         ref_name: ${{ github.ref_name }}
 
+    - name: Switch to HEAD of version branch for tags
+      # Tags aren't necessarily made to the HEAD of the version branch.
+      # The documentation to be published is always on the HEAD of the release branch.
+      if: steps.has-matching-release-tag.outputs.bool == 'true' && github.ref_type == 'tag'
+      env:
+        GITHUB_REF: ${{ github.ref }}
+        RELEASE_BRANCH_REGEXP: ${{ inputs.release_branch_regexp }}
+      run: |
+        branch="$(./publish-technical-documentation-release/determine-release-branch "${RELEASE_BRANCH_REGEXP}" "${GITHUB_REF}")"
+
+        if [[ -z "${branch}" ]]; then
+          echo "No release branch found for tag ${GITHUB_REF} matching ${RELEASE_BRANCH_REGEXP}. Exiting."
+
+          exit 1
+        fi
+
+        git switch --detach "origin/${branch}"
+      shell: bash
+
     - name: Sync to the website repository (release)
       if: steps.has-matching-release-tag.outputs.bool == 'true'
       uses: ./.github/actions/website-sync

publish-technical-documentation-release/determine-release-branch

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+
+set -euf -o pipefail
+
+function usage {
+  cat <<EOF
+Return the first release branch matching the provided branch regular expression that contains the provided tag.
+
+Usage:
+  $0 <BRANCH REGEXP> <TAG>
+
+Examples:
+  $0 '^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.x$' v11.3.1
+EOF
+}
+
+if [[ $# -ne 2 ]]; then
+  usage
+
+  exit 2
+fi
+
+BRANCH_REGEXP="$1"
+TAG="$2"
+
+for branch in $(git branch -a --contains "tags/${TAG}"); do
+  branch="${branch#remotes/origin/}";
+
+  if [[ "${branch}" =~ ${BRANCH_REGEXP} ]]; then
+    echo "${branch}";
+
+    exit 0;
+  fi;
+done
+
+exit 1

vale/.vale.ini

@@ -1,6 +1,5 @@
 MinAlertLevel = suggestion
-Packages = Google, https://github.com/errata-ai/Hugo/releases/download/v0.2.0/Hugo.zip, Readability
-StylesPath = /etc/vale/styles
+Packages = Grafana
+
 [*]
 BasedOnStyles = Grafana
-TokenIgnores = (<http[^\n]+>+?), \*\*[^\n]+\*\*

vale/Dockerfile

@@ -21,23 +21,17 @@ RUN mv reviewdog /out
 ################################################################################
 FROM jdkato/vale:v3.8.0
 
-ENV DICPATH=/etc/vale/dictionaries
+COPY --from=reviewdog /out/reviewdog /bin
+
+# Git is useful for reporting with reviewdog.
+RUN apk add --no-cache git
 
 RUN mkdir -p /etc/vale
+WORKDIR /etc/vale
 
-COPY Google /etc/vale/styles/Google
-COPY Grafana /etc/vale/styles/Grafana
+COPY .reviewdog.yml /etc/vale/.reviewdog.yml
 COPY .vale.ini /etc/vale/.vale.ini
-COPY .vale-config /etc/vale/.vale-config
-COPY config /etc/vale/styles/config
-COPY dictionaries /etc/vale/dictionaries
+COPY Grafana /etc/vale/Grafana
 COPY rdjsonl.tmpl /etc/vale/rdjsonl.tmpl
-COPY .reviewdog.yml /etc/vale/.reviewdog.yml
 
-# Git is useful for reporting with reviewdog.
-RUN apk add --no-cache git
-
-COPY --from=reviewdog /out/reviewdog /bin
-
-WORKDIR /etc/vale
 RUN vale sync

vale/Google/AMPM.yml

@@ -4,6 +4,6 @@ link: "https://developers.google.com/style/word-list"
 level: error
 nonword: true
 tokens:
-  - '\d{1,2}[AP]M'
-  - '\d{1,2} ?[ap]m'
+  - '\d{1,2}[AP]M\b'
+  - '\d{1,2} ?[ap]m\b'
   - '\d{1,2} ?[aApP]\.[mM]\.'

vale/Google/EmDash.yml

@@ -6,7 +6,7 @@ level: error
 action:
   name: edit
   params:
-    - remove
+    - trim
     - " "
 tokens:
   - '\s[—–]\s'