Release blog + upgrade manifest: render breaking-change detect blocks from a single source (DRY)

[chalin]

Background

In 0.15.0 we shipped two parallel artifacts for upgrade guidance:

• Human-readable blog: Release 0.15.0 report and upgrade guide — narrative breaking-change sections with Applies if… gates and prose action checklists.
• Machine-readable manifest (experimental, introduced in #PR-PLACEHOLDER): /upgrades/0.15.0.yaml — structured detect predicates, references, peer versions, and sanity checks intended for tooling and AI-agent consumption.

These two artifacts are currently independent and risk drifting (version pins, breaking-item ids, anchor names, detect recipes can all skew between the blog and the manifest as releases pile up). We accepted that risk for 0.15.0 to keep the change small and ship the manifest as a first step.

Goal for 0.16.0

Make the manifest the single source of truth for the structured bits, and have the release blog render them inline via Hugo data + a small set of shortcodes. The blog stays prose for narrative sections; structural data (versions, detect commands, applies-if gates, partial links, per-item references) is rendered from data/upgrades/<version>.yaml so authors maintain one file per release.

Proposed scope

• Promote docsy.dev/static/upgrades/0.15.0.yaml to a Hugo data file under docsy.dev/data/upgrades/0.15.0.yaml, and (re-)expose it as a static asset at /upgrades/<version>.yaml (e.g. via Hugo `outputs` or a copy step) so agent-facing URLs remain stable.
• Define and document the schema (`schema: docsy-upgrade-manifest/v1`): `from`, `to`, `peer`, `breaking[]` (with `id`, `title`, `summary`, `applies-if`, `detect`, `actions`, `references`), `sanity[]`, `rollback`. Detect rule kinds: `grep`, `file-exists`, `config-key-present`, `config-multilingual`, plus `any`/`all` combinators. The 0.15.0 manifest is the working seed.
• Author shortcodes (working titles): `upgrade-versions`, `upgrade-applies-if`, `upgrade-detect`, `upgrade-actions`. Each takes a manifest `id` and renders the corresponding structured bit inline. Output should match the existing blog formatting so the visual change is minimal.
• Add a small CSS rule for the rendered detect block (monospace, copy-button if cheap).
• Refactor the 0.15.0 blog to use the shortcodes (and likely backport to verify nothing visual regresses for indexed/archived versions).
• Document the workflow in maintainer-notes under the release-prep audit section so authors know to edit the manifest first, then the blog narrative.
• Add a CI check that validates the manifest schema and that referenced anchors (`/blog/2026/X.Y.Z/#anchor`) resolve.

Out of scope (future)

• An official Docsy upgrade skill / CLI (`docsy-upgrade`) that consumes the manifest. Once the schema stabilizes through 0.16.0+, a separate effort can package the skill — possibly as a Claude Code skill, GitHub action, or stand-alone CLI.
• Auto-fix transforms for deterministic migrations (e.g. the multilingual `/community/` → `//community/` rewrite under stated conditions). Would belong with the skill, not the manifest itself.

Why now

The 0.15.0 manifest is a first step, not a foundation. If we wait until 0.17.0 to DRY this up, we'll have at least three drifted copies and a much larger refactor. Doing it during 0.16.0 — while we have only one manifest in the wild — is the cheapest moment to lock in the workflow.

References

• 0.15.0 release blog
• 0.15.0 upgrade manifest (experimental)
• Maintainer notes: Release-prep audit

[chalin]

Schema gaps to address in v1

While dogfooding the 0.15.0 manifest as agent prompt input, a few specific friction points surfaced. Useful as a punch list / reference document, less so for autonomous deterministic execution. Items to address as the schema matures into v1:

1. Declare regex flavor. Detect rules use POSIX ERE in 0.15.0 but the manifest doesn't say so. Different runners (grep -E, ripgrep, Go regexp, JS) diverge on character classes and word-boundary anchors. Add a top-level regex-flavor: ERE (or per-rule override).

2. Declare path roots. paths: [content/, layouts/] is implicitly project-root-relative — needs to be stated. Same for any future config-paths style fields.

3. Locate Hugo configs explicitly. kind: config-key-present and kind: config-multilingual give no hint where to look. Hugo configs sprawl across hugo.{toml,yaml,json} at the project root, config/_default/, and per-environment/profile dirs. Either add a config-paths: list per rule or specify "follow Hugo's resolution rules and inspect the merged config" as the v1 default. The same applies to keys like params.versions that need to be evaluated against the merged config rather than any single file.

4. Replace the informal context: field with a structured form. Today context: under params.links is prose — useful to a human, opaque to an agent. Upgrade to e.g. under: params.links with the runner expected to confirm the regex match falls within that key's subtree of the parsed config, or drop the field entirely if a stricter kind: config-value-matches rule covers the use case.

5. Distinguish guidance from automation. Action lists are imperative ("Review", "Diff", "Recheck") — appropriate for a checklist, not actionable for an autonomous transform. v1 could add an optional transform field for deterministic migrations (e.g., the /community/ → /<default-lang>/community/ rewrite under stated conditions). Items without a transform remain advisory.

6. Pin the schema URL. Tooling will want to fetch a JSON Schema for validation. Plan a stable URL (e.g. https://www.docsy.dev/schemas/upgrade-manifest/v1.json) and version it via the existing schema: field.

Captured these here so the v1 schema work can address them up front rather than chasing them after the fact.