Repository navigation
docs(dns): fix style findings in the DNS guide - #377
Draft
mknell-godaddy wants to merge 2 commits into
Draft
mknell-godaddy wants to merge 2 commits into
mknell-godaddy wants to merge 2 commits into
Conversation
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.
Contributor
There was a problem hiding this comment.
🟡 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
setsection 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
| | `--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 | |
Collaborator
Author
There was a problem hiding this comment.
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.

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.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".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.set --replace-conflicting-typesbelow" now points to thesetsection by name.Checked
dns.mdhas no findings.docs, and the README).cargo testlocally, 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.