Skip to content

docs(dns): fix style findings in the DNS guide - #377

Draft
mknell-godaddy wants to merge 2 commits into
mainfrom
docs/dns-guide-style
Draft

mknell-godaddy wants to merge 2 commits into
mainfrom
docs/dns-guide-style

Conversation

@mknell-godaddy

Copy link
Copy Markdown
Collaborator

Why

The new guide style rules report 26 findings in dns.md. A later change makes the check blocking, so each guide has to pass first. This is the second guide, split out so the DNS reviewers see only their own text. The first was shopping (#376).

What changed

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

  • Em dashes become periods or commas.
  • The summary: line drops its em dash and has no colon, so the YAML stays valid. It now reads "Manage DNS records with gddy by listing, adding, setting, and deleting them".
  • Headings use the imperative form: "Manage DNS with gddy", "List records", "Add records", "Replace records", "Delete records". The rule's list of gerunds only matches three of these, but changing all five keeps the guide consistent.
  • "does not", "is not" and "are not" become contractions, and "e.g." becomes "for example".
  • Slashes that stood for "and" now say "and": "type and name", "created and failed", "replace, create, or delete". The CAA row now says the data carries "the CA domain, which is the record value".
  • Three passive phrases are active, and three sentences over 30 words are split.
  • "see set --replace-conflicting-types below" now points to the set section by name.

Checked

  • With the style rules from ci: add the guide style rules to the Vale check (non-blocking) #375, dns.md has no findings.
  • No Rust test reads this guide's text, and nothing links to the renamed headings (I searched the Rust sources, docs, and the README).
  • 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 26 findings in dns.md. A later change makes
the check blocking, so each guide has to pass first. This is the second guide,
split out so the DNS reviewers see only their own text.

What changed: wording only, each edit keeping its meaning. Em dashes became
periods, commas or a colon-free summary. Headings use the imperative form
("Manage DNS", "List records", "Add records", "Replace records", "Delete
records"), including two the rule's gerund list doesn't match, so the guide
reads the same throughout. "does not", "is not" and "are not" became
contractions, "e.g." became "for example", and slashes that stood for "and"
now say "and". Three passive phrases are active, and three sentences over 30
words are split.

The summary line now has no colon, so it stays valid YAML. The "see ... below"
pointer in the CNAME paragraph names the `set` section instead of "below".

No Rust files change. No test reads this guide's text, and nothing links to
the renamed headings.
Copilot AI balanced review requested due to automatic review settings November 16, 2026 20:47

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.

🟡 Changes recommended

The DNS guide incorrectly describes --data as a CA domain, although iodef takes a reporting URI, which could lead users to supply invalid values.

1 open issue
What changed in this PR

This PR updates the DNS command guide to align with the proposed guide style rules ahead of blocking checks. No Rust code or command behavior changes.

Changes:

  • Uses imperative headings, contractions, and simpler punctuation.
  • Splits long sentences and replaces passive phrasing.
  • Clarifies the reference to the set section and revises type-specific flag descriptions.
File Description
rust/​src/​dns/​guides/​dns.md Updates DNS guide wording and headings to follow the new style rules.

Review effort: Balanced

Comment thread rust/src/dns/guides/dns.md Outdated
| `--priority` | `MX`, `SRV` | |
| `--port`, `--weight`, `--protocol`, `--service` | `SRV` | |
| `--flag`, `--tag` | `CAA` | `--tag` is required for CAA (e.g. `issue`, `issuewild`, `iodef`); `--data` carries the CA domain/value |
| `--flag`, `--tag` | `CAA` | CAA records require `--tag` (for example `issue`, `issuewild`, `iodef`), and `--data` carries the CA domain, which is the record value |

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

Fixed in bbf484f. The row now says --data carries the value for that tag, with a CA domain as the example. The earlier wording was my rewrite of "CA domain/value" and it was wrong for iodef, which takes a reporting URL.

Why: the guide lists issue, issuewild and iodef as CAA tags. For issue and
issuewild the value is a CA domain, but for iodef it is a reporting URL such as
a mailto: address. My earlier rewrite of "the CA domain/value" said the value
is the CA domain, which is wrong for iodef and could lead a reader to enter an
invalid value. A review comment caught it.

Decision: say --data carries the value for the selected tag, with a CA domain
as the example. That keeps the original's looseness without the false claim.
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