Skip to content

feat: enable Coder.Please Vale rule - #30789

Merged
nickvigilante merged 2 commits into
mainfrom
vigilante/docs-1281-add-coderplease-vale-rule
Oct 24, 2026
Merged

nickvigilante merged 2 commits into
mainfrom
vigilante/docs-1281-add-coderplease-vale-rule

Conversation

@nickvigilante

@nickvigilante nickvigilante commented Oct 14, 2026 •

Copy link
Copy Markdown
Collaborator

Depends on #30782.

Adds Coder.Please, a Vale rule that enforces Leave out "please".

  • Flags \bplease\b, ignoring case.
  • Severity: warning. Scope: docs/** except docs/.style/style-guide/**.
  • Baseline: 31 findings in 24 pages (23 hand-written plus the generated configuration reference), 0 after cleanup.
  • Code spans and fenced code blocks are skipped by Vale, so quoted product text such as Please try again later stays untouched, as the guide asks.

Commits

  1. docs: leave "please" out of instructions: rewrites each use as a direct imperative and keeps the meaning.
    It also fixes the one generated page that had a finding.
    docs/admin/setup/configuration-reference.md comes from the telemetry group description in codersdk/deployment.go, so the cleanup edits that source and the golden files (cli/testdata/coder_server_--help.golden, cli/testdata/server-config.yaml.golden, enterprise/cli/testdata/coder_server_--help.golden) regenerated with go test -update.
  2. feat(docs/.style): enable Coder.Please Vale rule: adds the rule, flips the footer to enforced, adds the checks-table row, and updates the coverage counts.

No .vale.ini change is needed, and no generated page is excluded.

Linear: DOCS-1281

Decision log
  • An existence rule with one \bplease\b token. Word boundaries keep pleasant and displeasing out.
  • warning rather than error, because a quoted product message can legitimately contain the word outside code font.
  • Generated pages: fixed in Go source instead of excluded, because only one string was affected and the text reads better without it.
  • URL query strings such as body=please+enter+your+request+here aren't flagged, because Vale skips link destinations.
  • The README sentence about rows, checks, and sections moves from 7, 10, and 9 to 8, 11, and 10 for the new row.

Test cases (fixtures under /tmp/please-test/, not committed), run with LF and CRLF line endings, 6 findings each:

  • Flagged: sentence-initial Please, trailing , please., PLEASE, a blockquote, a list item, a heading.
  • Not flagged: a code span containing Please try again later, a fenced code block containing Please install curl, pleasant, displeasing.

Checks:

  • vale --output=line docs/ reports 0 Coder.Please findings.
  • go run ./scripts/styleclaims passes.
  • The pre-commit hooks pass on both commits (gen, lint/go, lint/ts, markdown, emdash, style-claims, typos).
  • go test ./cli -run 'Test(CommandHelp|ServerYAML)' and go test ./enterprise/cli -run TestEnterpriseCommandHelp pass with the updated golden files.

Generated by Coder Agents on behalf of @nickvigilante.

@linear-code

linear-code Bot commented Oct 14, 2026

Copy link
Copy Markdown

DOCS-1281

@nickvigilante
nickvigilante force-pushed the vigilante/docs-1281-add-coderplease-vale-rule branch from a30a9a4 to 6cefe5d Compare October 14, 2026 20:55
Base automatically changed from vigilante/docs-1282-style-guide-add-missing-rules-from-the-docs-style-guide to main October 16, 2026 13:53
@nickvigilante
nickvigilante marked this pull request as ready for review October 23, 2026 05:44

@ianjevans ianjevans left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lgtm

Rewrites 31 prose uses of "please" as direct imperatives, plus the telemetry group description in codersdk and the golden files and configuration reference generated from it.
Flags "please" at warning severity and flips the style guide footer from planned to enforced.
@nickvigilante
nickvigilante force-pushed the vigilante/docs-1281-add-coderplease-vale-rule branch from ec79154 to 3c3724e Compare October 24, 2026 02:56
@nickvigilante

Copy link
Copy Markdown
Collaborator Author

The Analyze PR for Documentation Updates Needed (doc-check) job timed out after 40 minutes waiting for its agent chat to finish, so no review was posted. All required checks pass. The same timeout hit several PRs around the same time, so this looks like a doc-check service problem rather than anything in this branch. Re-run the job if you want the doc review before merging.

Generated by Coder Agents on behalf of @nickvigilante.

@nickvigilante
nickvigilante merged commit 58d19d7 into main Oct 24, 2026
32 of 34 checks passed
@nickvigilante
nickvigilante deleted the vigilante/docs-1281-add-coderplease-vale-rule branch October 24, 2026 04:18
@github-actions github-actions Bot locked and limited conversation to collaborators Oct 24, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants