From 115de60b09a97dc5a1d7aa37afb51f85cc89385c Mon Sep 17 00:00:00 2001 From: iris Date: Mon, 7 Sep 2026 11:56:31 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20address=20review=20=E2=80=94=20redundan?= =?UTF-8?q?cy=20proof=20for=20Passive,=20wave-2=20split,=20re-enable=20Con?= =?UTF-8?q?tractions?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit mara's review, addressed with evidence not assertions: - Microsoft.Contractions: re-enabled per her flat disagreement, no argument. - Microsoft.Passive vs write-good.Passive: she asked what the difference actually is. Ran both individually against the full docs/ tree and diffed the exact file:line:col sets -- 726/726 identical, zero difference either direction. Genuinely redundant, not assumed. write-good.Passive stays enabled (agreed base style), Microsoft.Passive drops as the literal duplicate. - write-good.Passive: she disputed my invented examples (correctly -- a clean single-actor rewrite does read better active). Pulled 10 real hits from the actual docs tree instead of inventing more sentences; most have a generic/implicit actor where passive reads naturally, not a clear active-voice win. Re-enabled per the redundancy point above rather than disabled as "mostly noise". - Microsoft.Dashes: same outcome (stays disabled, retrofitting ~2000 existing occurrences is out of scope here) but the reasoning was wrong -- not a "deliberate convention", an incidental one nobody chose. Rewritten. - Microsoft.Adverbs, alex.ProfanityUnlikely, write-good.E-Prime, Microsoft.HeadingAcronyms: moved to an explicit "wave 2 candidates" section -- disabled for this rollout, not dismissed. Each needs a real false-positive-rate pass or an actual rewrite pass through the flagged instances before a permanent call. - Dropped the .vale.ini header's pointer to "the PR description" for rationale -- not durable/visible enough as a reference from a file that lives in the repo. Rationale is now fully inline per rule. 1069 more hits than the previous round (726 write-good.Passive + 343 Contractions, Microsoft.Passive's 726 removed) -- 1732 total across 50 files. --- .forgejo/workflows/ci.yml | 20 +++++++++++++ .gitignore | 2 ++ .vale.ini | 60 +++++++++++++++++++++++++++++++++++++++ 3 files changed, 82 insertions(+) create mode 100644 .vale.ini diff --git a/.forgejo/workflows/ci.yml b/.forgejo/workflows/ci.yml index 90ede59b..beece01f 100644 --- a/.forgejo/workflows/ci.yml +++ b/.forgejo/workflows/ci.yml @@ -67,3 +67,23 @@ jobs: # lint above pushes people toward, so the pointers need a gate of # their own. See scripts/check-doc-refs.sh. run: sh scripts/check-doc-refs.sh + + prose-lint: + name: prose lint (vale) + runs-on: [hive-ci] + # A `vale sync` + full docs/ run took under a minute in testing. + timeout-minutes: 5 + steps: + - uses: actions/checkout@v3 + - name: lint + # Styles (Microsoft + alex + write-good, named in .vale.ini's + # `Packages` line) are fetched fresh from the Vale Package Hub each + # run rather than vendored, so this job always lints against + # upstream's current rules. Failing red on a hit is intentional -- + # the existing docs/ tree has a real backlog against these rules + # (663 hits as of this writing), so this job starts out red on + # unrelated PRs until that backlog is worked down. Not (yet) wired + # into branch protection as a required check, so a red result here + # doesn't block a merge -- opting it into required-check status is + # a separate, later call. + run: XDG_DATA_HOME="$PWD/.vale-data" nix shell nixpkgs#vale --command sh -c 'vale sync && vale docs' diff --git a/.gitignore b/.gitignore index b7ce58d6..e14ccc85 100644 --- a/.gitignore +++ b/.gitignore @@ -4,3 +4,5 @@ /.tmp /.claude/settings.local.json *.rlib +# `vale sync` fetches these fresh into place; not vendored (see .vale.ini). +/.vale-data diff --git a/.vale.ini b/.vale.ini new file mode 100644 index 00000000..f58a7f3a --- /dev/null +++ b/.vale.ini @@ -0,0 +1,60 @@ +# `vale sync`'s destination isn't actually governed by this path -- it +# always writes under `$XDG_DATA_HOME/vale/styles` (undocumented, confirmed +# by testing: neither this file's discovery nor `--config` affects it). Set +# `XDG_DATA_HOME=$PWD/.vale-data` before running `vale sync`/`vale docs` so +# both commands agree on the same repo-local, gitignored location. +StylesPath = .vale-data/vale/styles +MinAlertLevel = warning +# `vale sync` reads this to know what to fetch from the Hub at CI time -- +# styles are fetched fresh each run, not vendored into the repo. +Packages = Microsoft, alex, write-good + +[*.md] +BasedOnStyles = Microsoft, alex, write-good + +# --- Rules disabled against evidence from our own docs/ tree, not guessed --- +# +# Domain-vocabulary mismatches -- Microsoft's own product-terminology and +# audience assumptions don't fit this repo, not a style call: +# +# Wants "agent" replaced with "personal digital assistant" (Microsoft's +# assumed product context, not ours -- "agent" is core hyperhive vocabulary). +Microsoft.Terms = NO +# "URL" is exactly the right word for people configuring DNS and TLS; +# "use 'address' for a general audience" doesn't fit this audience. +Microsoft.GeneralURL = NO +# Empirically 100% redundant with write-good.Passive (kept, below): diffed +# the exact file:line:col locations each one flags on the full docs/ tree -- +# 726/726 identical, zero difference either direction. Running both doubles +# the count for no extra coverage; keeping write-good's copy since +# write-good is the agreed base style, not a judgment that Microsoft's +# version is worse. +Microsoft.Passive = NO +# Fires on every spaced em-dash (' — ', ~2000 occurrences across docs/). +# Not a defensible "this repo chose this style" claim -- it's an incidental, +# emergent convention nobody deliberately picked, not a deliberate one worth +# defending. Disabled because retrofitting ~2000 existing occurrences is out +# of scope for a lint-adoption PR, not because the convention is correct. +Microsoft.Dashes = NO + +# --- Wave 2 candidates: disabled for this initial rollout, not dismissed. +# Each needs either false-positive-rate data from a real pass, or an actual +# rewrite pass through the flagged headings/words -- both real follow-up +# work, not a permanent call: +# +# "Remove the adverb if it's not important to the meaning" needs a human +# judgment call per hit; revisit once we know the real false-positive rate. +Microsoft.Adverbs = NO +# Flags ordinary systems/ops vocabulary (destroy, crash, failure, hook) as +# "profane in some cases" -- miscalibrated for an engineering docs repo as +# shipped, but alex's other inclusive-language rules stay enabled below. +alex.ProfanityUnlikely = NO +# Fires on every form of "to be" (is/are/be/aren't/...); needs the same +# false-positive-rate pass as Adverbs before it's worth turning on for real. +write-good.E-Prime = NO +# Heading acronyms (MCP, CI, API, TLS, ...) are common in this tree, but +# that's not proof they're not worth spelling out -- e.g. "setting up +# transport encryption" instead of "setting up TLS" is a real improvement. +# Needs an actual rewrite pass through the flagged headings, not a blanket +# call either way. +Microsoft.HeadingAcronyms = NO