Skip to content

docs(pat): fix style findings in the authentication guide - #380

Draft
mknell-godaddy wants to merge 1 commit into
mainfrom
docs/pat-guide-style
Draft

mknell-godaddy wants to merge 1 commit into
mainfrom
docs/pat-guide-style

Conversation

@mknell-godaddy

Copy link
Copy Markdown
Collaborator

Why

The new guide style rules report 32 findings in auth.md. A later change makes the check blocking, so each guide has to pass first. This is the third guide, after shopping (#376) and DNS (#377), split out so the PAT reviewers see only their own text.

What changed

Wording edits in rust/src/pat/guides/auth.md. Each keeps its meaning.

  • Em dashes become colons or periods. "via" becomes "with".
  • "e.g." becomes "for example". "CI/CD" becomes "CICD", because the style rules allow a slash only for rates and ratios.
  • "do not", "does not", "is not" and "have not" become contractions. Where the word "not" was bold for emphasis, the bold moves to the contraction ("doesn't").
  • Two sentences over 30 words are split. "Once you have logged in" becomes "After you log in". Two passive phrases are active.
  • Headings use the imperative: "Create a PAT", "Store a PAT in the CLI", "List and remove PATs", "Use PATs in CI". The rule's list of gerunds matches only two of these, but changing all four keeps the guide consistent.

For reviewers

  • "CICD" is a deliberate spelling, per the style decision. Say if you'd rather use another form.
  • Two sentences change tense ("will open" becomes "opens", "is stored" becomes "gddy stores"). The meaning is the same.

Checked

  • With the style rules from ci: add the guide style rules to the Vale check (non-blocking) #375, auth.md has no findings.
  • The one link inside the guide, to "How the CLI chooses a credential", points to a heading I didn't change. I searched the Rust sources, docs and the README for the old headings and found no links.
  • No Rust files change, and I couldn't run cargo test locally, so the test run here is CI's.

The rules are in #375, which isn't merged yet. This change doesn't depend on them.

Why: the guide style rules report 32 findings in auth.md. A later change makes
the check blocking, so each guide has to pass first. This is the third guide,
after shopping and DNS, and it is split out so the PAT reviewers see only
their own text.

What changed: wording only, each edit keeping its meaning. Em dashes became
colons or periods, "via" became "with", "e.g." became "for example", and
"CI/CD" became "CICD". Spelled-out "do not", "does not", "is not" and "have
not" became contractions, and the three "does not" sentences that bolded the
word keep the emphasis on the contraction. Two sentences over 30 words are
split, "Once you have logged in" became "After you log in", and two passive
phrases are active. Headings use the imperative ("Create a PAT", "Store a PAT
in the CLI", "List and remove PATs", "Use PATs in CI"), including two the
rule's gerund list doesn't match, so the guide reads the same throughout.

The only in-guide anchor link points to "How the CLI chooses a credential",
which is unchanged. No Rust files change and no test reads this guide's text.
Copilot AI balanced review requested due to automatic review settings November 16, 2026 21:44

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🟢 Approval recommended

No active review issues remain for the authentication guide’s style-focused revisions.

No open issues 🎉

What changed in this PR

Updates the authentication guide to align with the planned guide style rules, without changing CLI behavior or authentication instructions.

Changes:

  • Simplifies wording, punctuation, and long sentences.
  • Uses imperative headings for PAT tasks.
  • Applies contractions and the deliberate “CICD” spelling consistently.
File Description
rust/​src/​pat/​guides/​auth.md Revises OAuth and PAT documentation for guide style compliance.

Review effort: Balanced

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants