Skip to content

docs: use sentence case for headers#583

Merged
tomarra merged 6 commits into
mainfrom
docs/heading-sentence-case
Jul 2, 2026
Merged

docs: use sentence case for headers#583
tomarra merged 6 commits into
mainfrom
docs/heading-sentence-case

Conversation

@tomarra

@tomarra tomarra commented Jul 2, 2026

Copy link
Copy Markdown
Contributor

Status

READY

Description

Per the marketing content guidelines (see #576), headers should use sentence case, not Title Case. Fixes 169 headings across 44 files.

This one took more digging than the others — Vale's capitalization rule has some real quirks I only found by testing directly against it rather than guessing. Details below since they matter for review.

Left untouched — compound product/brand names where fixing the flagged word in isolation makes the phrase read worse than leaving it alone (e.g. "Azure key Vault", "app Store connect"):

  • "Azure Key Vault", "GCP Cloud KMS", "Create a release in App Store Connect"
  • "How does this relate to Firebase Remote Config or Launch Darkly?"
  • "How does this relate to Flutter Hot Reload?" (Flutter's own name for the feature)

Left untouched — three "Flutter vs. X" headings: Vale's capitalization rule flags any heading containing "vs" or "vs." regardless of what surrounds it (verified with isolated test cases — even a heading of just "Testing vs here" gets flagged). This isn't configurable via the exceptions list; it's baked into the rule. The content itself (Flutter vs. the competition, Flutter vs. native development) is already correctly cased; Flutter vs. React Native is left as-is since "React Native" is itself a proper noun.

Left untouched — four "code push" FAQ headings (e.g. "Does code push require the internet to work?"): enabling the Vocab-driven proper-noun rule (for the Shorebird/Flutter/Code Push guideline) has a side effect — it makes Vale's capitalization rule also flag any heading containing a mis-cased vocab term, even when the heading has no actual sentence-case violation. These four headings get fixed by #579 (capitalizing "code push" → "Code Push"), which resolves this side effect too. No separate edit needed here.

Reverted to Title Case — a 3-item numbered list ("1. The Status Enum", "2. The Single State Class", "3. The Events"): oddly, Vale stops flagging #2 once lowercased but keeps flagging #1 and #3 despite identical structure (confirmed this is a real Vale inconsistency, not a mistake on my end). Rather than leave the list looking inconsistent, I reverted all three to their original Title Case.

New proper nouns discovered and added to the exceptions list (not previously recognized): Stripe, Fastfile, BuildContext, RenderObject, Apple, 1Password, AOT, GuardSquare, LTS, ExportOptions.plist, Skia, Impeller. Also fixed two headings using lowercase "fastlane" where the tool name should be capitalized ("Using Fastlane on CI/locally").

Follow-up needed: those new exceptions need to land in .vale/styles/Shorebird/Headings.yml on the tooling PR (#576) too — otherwise they'll show up as false positives again once both PRs merge. I'll push that update to #576 separately.

This is one of several small content PRs split out of #576 so the Shorebird.Headings check can eventually be made blocking without a giant, hard-to-review PR.

Test plan

Per the marketing content guidelines, headers should use sentence
case, not Title Case. Fixes 169 headings across 44 files.

Left several categories of heading untouched, all confirmed by
testing directly against Vale rather than guessing:

- Compound product/brand names where per-word exception matching
  breaks down and partially-casing the phrase reads worse than the
  original: "Azure Key Vault", "GCP Cloud KMS", "App Store Connect",
  "Firebase Remote Config", "Launch Darkly", "Flutter Hot Reload".
- Three "Flutter vs. X" headings: Vale's capitalization rule flags
  any heading containing "vs"/"vs." regardless of surrounding case,
  a hardcoded quirk that isn't configurable via the exceptions list.
- Four "code push" FAQ headings (e.g. "Does code push require the
  internet to work?"): enabling the Vocab-driven proper-noun rule
  causes Vale's capitalization rule to also flag any lowercase vocab
  term (Shorebird/Flutter/Code Push) in a heading, even though sentence
  case itself has no violation here. These already get fixed by the
  proper-noun-capitalization PR; no separate edit needed here.
- Three sequential numbered headings ("1. The Status Enum", "2. The
  Single State Class", "3. The Events"): Vale's algorithm inexplicably
  passes #2 once lowercased but keeps flagging #1 and #3 with
  identical structure. Reverted all three to Title Case to keep the
  numbered list visually consistent rather than partially complying.

Also discovered and fixed real proper nouns that weren't yet
recognized by the Headings rule's exceptions list (Stripe, Fastfile,
BuildContext, RenderObject, Apple, 1Password, AOT, GuardSquare, LTS,
ExportOptions.plist, Skia, Impeller) and two headings using lowercase
"fastlane" where the tool name should be capitalized ("Using Fastlane
on CI/locally"). These exceptions need to land in the tooling PR
(#576) as well, or they'll show as false positives again once these
two PRs both merge.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
tomarra added a commit that referenced this pull request Jul 2, 2026
Adds Stripe, Fastfile, BuildContext, RenderObject, Apple, 1Password,
AOT, GuardSquare, LTS, ExportOptions.plist, Skia, and Impeller to the
Headings rule's exceptions list. These surfaced while applying the
sentence-case fixes in #583 — without them, this check will flag
legitimate proper nouns as false positives once both PRs merge.
@tomarra tomarra requested a review from dawn-ducky July 2, 2026 17:49
tomarra added a commit that referenced this pull request Jul 2, 2026
Adds TokenIgnores for headings intentionally left as Title Case in
PR #583:
- "vs"/"vs." trips Vale's capitalization rule unconditionally,
  regardless of surrounding case or the exceptions list.
- Compound product/brand names (Azure Key Vault, GCP Cloud KMS, App
  Store Connect, Firebase Remote Config, Launch Darkly, Hot Reload)
  where per-word exception matching breaks the phrase apart.
- Three numbered-list headings kept as Title Case for visual
  consistency with their siblings (see #583 for why).

Without this, these ~9 headings would show as permanent findings
forever, even after all the content PRs merge, making it impossible
to ever flip this check to blocking.
tomarra added a commit that referenced this pull request Jul 2, 2026
Bumps both custom rules from warning to error severity and flips
fail_on_error to true in CI, so they now actually gate merges instead
of just annotating PRs.

Vale.Terms (proper-noun capitalization) is explicitly downgraded to
warning via `Vale.Terms = warning`, staying non-blocking. It doesn't
respect code-fence exclusion the way our custom scope:text rules do,
and a TokenIgnores pattern matching one occurrence of a shell command
(e.g. `shorebird release android`) intermittently fails to suppress a
second, identical occurrence elsewhere in the same file - confirmed
with minimal reproductions, not a config mistake. Findings are still
reported, just don't block.

Shorebird.SecondPerson stays at warning too, since that guideline's
content work hasn't happened yet.

IMPORTANT: this branch's own CI will fail until #583 (heading
sentence-case fixes) merges - this branch still has the original
Title Case headings. Do not merge this PR before #583. Verified the
full combination (this branch + main + #583 + #584) passes cleanly
with fail_on_error: true.
Comment thread src/content/docs/code-push/guides/hybrid-apps/ios.mdx
Comment thread src/content/docs/flutter-concepts/architecture-trees.mdx
Comment thread src/content/docs/flutter-concepts/architecture-trees.mdx
Comment thread src/content/docs/flutter-concepts/architecture-trees.mdx Outdated
@tomarra tomarra merged commit a0bd66a into main Jul 2, 2026
3 checks passed
@tomarra tomarra deleted the docs/heading-sentence-case branch July 2, 2026 19:07
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