Skip to content

Lean and DRY pass over the 0.16.0 release artifacts#2682

Merged
chalin merged 12 commits into
google:mainfrom
chalin:chalin-m24-0.16.0-post-review-2026-0718
Jul 19, 2026
Merged

Lean and DRY pass over the 0.16.0 release artifacts#2682
chalin merged 12 commits into
google:mainfrom
chalin:chalin-m24-0.16.0-post-review-2026-0718

Conversation

@chalin

@chalin chalin commented Jul 18, 2026

Copy link
Copy Markdown
Collaborator

Applies the Content placement guidance (one home per fact; lean and DRY) to the 0.16.0 release artifacts:

  • Defers restated mechanics to their canonical homes: the release post links the Hugo guide's language-API renames, the docs' fresh-install setup and PostCSS guidance, and the official support policy instead of restating them.
  • Trims changelog entries to the what-changed bar: drops upgrade advice, the favicon filename list, and PostCSS behavior detail.
  • Homes the Browserslist defaults compatibility statement in the docs (Install PostCSS).
  • Reworks the post's Release summary as a selective ToC and removes intra-page restatements.
  • Applies the same pass to the companion Hugo 0.158+ upgrade guide, making the release post the sole owner of the Hugo version requirements.
  • Blog posts now render Hugo versions time-insensitively, frozen as page params in their front matter; this fixes the 0.152 guide, whose published recommendation had silently drifted from 0.157.0 to 0.160.1. Documented in the maintainer notes and guarded by test:hugo-versions: frozen params must be effective (where Hugo resolves them), draft posts must freeze the currently declared values, and draft-guide title bounds must cover the frozen target.

Preview: release post · Hugo guide · changelog

chalin added 12 commits July 18, 2026 18:51
Cross-page DRY pass over the 0.16.0 release artifacts (one home per fact):

- Release post: links the Hugo guide's language-API renames instead of
  restating them; replaces the fresh-clone setup recipe with the
  existing-install update step and a link to Other installation options;
  links Install PostCSS; the version footnote links the official support
  policy instead of restating it.
- Changelog: drops upgrade advice from the Hugo-floor entry (the google#2593
  citation moves to the language-API entry); trims the favicon filename
  list and discovery restatement (docs own the reference detail);
  tightens the PostCSS entry.
- Docs: Install PostCSS now owns the Browserslist defaults compatibility
  statement (was stated only in the post and changelog).
- Reworks the Release summary as a selective ToC (one bullet per
  section with a glue clause), matching the 0.15.0 summary style;
  actions and details stay in their sections.
- Links the two unlinked skim items in Ready to Upgrade.
- Drops intra-page restatements: theme/package.json ownership was
  stated three times (npm-deps section is its home), and the shared
  chrome section stated the full-is-default fact three times and
  experimental twice in one paragraph.
- Compresses the nested-module-tag note to its user-relevant point.
Captures the review guidance applied to the 0.16.0 post in its
canonical home (Content placement): upgrade posts stay maximally
actionable yet lean, the release summary reads like a selective table
of contents, and each fact has one home section. Also spells out
'devs' (flagged by cspell).
Applies the same one-home-per-fact review as the release post:

- Removes the trailing 'Recommended minimum Hugo version' section: it
  restated the intro, the Hugo-version section, and the Upgrade section,
  and nothing links to it. Its one unique bit, the hugoVersion.min YAML
  shape, moves into the Hugo-version actions.
- Homes the hugo-extended and hvm install commands in the Upgrade
  section (they appeared twice); the Hugo-version actions link there.
- Collapses the node-tools body/actions near-verbatim duplication of
  the 0.163.2 and 0.163.3 fix conditionals: the actions own them.
- Drops vestigial 'upgrade to 0.160.1' advice from the amp-escaping
  and template-cleanup actions -- 0.160.1 is already the mandatory
  minimum -- and folds the link-render-hook shielding nuance into its
  action bullet.
- cSpell: adds contentbasename and downscaling, pre-existing words in
  this file that the spell check flags.
The release and Hugo-upgrade posts are companions, published and read
together, so the standalone-entry-point argument doesn't justify both
posts stating the Hugo floor and target with near-identical actions.

- Hugo guide: drop the Hugo-version section and its actions; the intro,
  a summary item, and internal anchors now link to the release post's
  Hugo section instead.
- Release post: absorb the unique detail (validated across the project,
  example site, and a large downstream site) and point its actions at
  the guide's install commands.
The 0.152 upgrade guide rendered its recommended minimum via the
hugoMinVersion site param, so the published post silently drifted from
0.157.0 to 0.160.1 when the param moved. Freeze the publish-time
literals.

Maintainer notes now state the rule: current-state pages (docs, the
changelog's official-support section) compute versions via the param
and the hugo-version shortcode; blog posts are historical snapshots and
hard-code literals.
Blog posts are historical snapshots, so they must render versions
time-insensitively — but scattering literals through a post makes
updates (say, for a patch release) a search-and-replace exercise.
Instead, declare each version a post repeats as a page param frozen in
its front matter: one field to edit, and since page params take
precedence over site params, the same param call is frozen in a post
and live in docs.

- 0.152 guide: freeze hugoMinVersion at its publish-time value
  (0.157.0), shadowing the site param it had silently drifted with.
- 0.16.0 and Hugo 0.158+ posts: render the validated upgrade target via
  a frozen hugoTarget page param; narrative facts about specific
  releases stay literal.
- Maintainer notes: document the rule.
- test:hugo-versions: posts must not use the live hugo-version
  shortcode, and any version param a post renders must be frozen in its
  front matter (red-proofed against the unfrozen 0.152 post).
Name the concept — the officially supported Hugo version, per the
changelog's official-support policy — rather than the param's role in
one post, and echo the hugoMinVersion form.
The rule's home is the maintainer notes and the freeze is
test-enforced; snapshot semantics for a version param in a dated post
need no per-post explanation. Trim the test comment to a pointer for
the same reason.
Companion posts declare hugoSupportedVersion independently, so a
patch-time bump could update one post and miss the other. Frozen
versions snapshot publish-time values: until a post is published they
must match the live declarations, which transitively keeps companions
in agreement. Dormant for published posts, whose values age by design.

Red-proofed: bumping one companion's frozen value fails only the new
test, with the missed post named.
- Drops the release post's Browserslist-defaults paragraph: the fact and the keep-PostCSS guidance live in the linked Install PostCSS docs.
- Generalizes the package-layout bullet to "runtime npm dependencies": the npm-deps section owns which packages theme/package.json declares.
- Matches frozen params only where Hugo resolves them — top-level front-matter fields or direct children of params: — so a deeper-nested param (silently ignored by Hugo) no longer passes as frozen.
- Requires draft-guide titles with an upper version bound (N.M.x) to cover the frozen hugoSupportedVersion, so advancing the target forces the guide's range and coverage to be reviewed.
- Narrows the maintainer notes and test comment to the version params that posts render, which is what the guard covers; narrative version literals stay literal.
@chalin
chalin merged commit 4d8d85e into google:main Jul 19, 2026
17 checks passed
@chalin
chalin deleted the chalin-m24-0.16.0-post-review-2026-0718 branch July 19, 2026 11:29
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.

1 participant