|
| 1 | +--- |
| 2 | +name: review-release-content |
| 3 | +description: Review a Quarto release changelog for completeness, placement and wording, and prepare website highlights or a release blog handoff before release. Use for release content preparation, rather than building or publishing a release. |
| 4 | +--- |
| 5 | + |
| 6 | +# Review release content |
| 7 | + |
| 8 | +Prepare the requested Quarto release content with verified claims. Derive the version, release scope and editorial emphasis from the current request and repository state. |
| 9 | + |
| 10 | +Choose the scope from the request: |
| 11 | + |
| 12 | +- For a changelog audit, check completeness across the release range and preserve entry identities while editing. |
| 13 | +- For highlights or a preliminary blog draft, use the changelog as input and verify the selected claims. A full omission audit is needed only when requested or when the source cannot support the draft. |
| 14 | +- For destination edits or a finished blog post, use the destination's own workflow and skills. This skill supplies release evidence and the handoff. |
| 15 | + |
| 16 | +## Establish the review scope |
| 17 | + |
| 18 | +Read `.claude/rules/changelog.md` in full before editing the changelog. It is the source of truth for changelog structure and style, including its Backports section. Read the applicable release checklist in `dev-docs/` for context when preparing website or announcement content; executing the release is a separate task. |
| 19 | + |
| 20 | +Identify the target `news/changelog-{version}.md`, intended release branch or candidate, previous stable release, and relevant commit range. Inspect local changes and upstream freshness before selecting a base. Record the refs and commits actually reviewed; do not assume the local default branch represents the candidate. |
| 21 | + |
| 22 | +Preserve a baseline of entry identities and contributor credits before reorganizing the changelog. Existing local release assessments can supply context, but their conclusions need current evidence before reuse. |
| 23 | + |
| 24 | +## Verify and edit the changelog |
| 25 | + |
| 26 | +Compare landed changes across the release range with the changelog, not just the URLs already present. Use history, PR diffs, bundled engine changelogs and dependency configuration to find omissions. Include changes that affect users or supported developer workflows; distinguish shipped dependencies from experiments and build spikes. Check whether the merge deliberately omitted an entry before adding it. |
| 27 | + |
| 28 | +For new or materially rewritten claims, establish the landed implementation and exact scope. Verify linked PRs are merged and their changes belong to the reviewed release. An open issue can track broader work than its landed fix: assess the narrow claim rather than treating issue closure as proof. |
| 29 | + |
| 30 | +For claims involving bundled extensions, metadata, localization, dependencies or accessibility tooling, consult the matching sources in [references/cli-guidance.md](references/cli-guidance.md). Read only the guidance needed to resolve the claim. |
| 31 | + |
| 32 | +### Regression fixes and backports |
| 33 | + |
| 34 | +`Regression fixes` signals fixes also backported to stable. A bug introduced in an older version is not sufficient evidence for placement there. |
| 35 | + |
| 36 | +- Before adding or moving an entry into this section, verify the stable backport is merged, using the stable history/changelog and backport PR where available. An open backport PR or backport label is insufficient. |
| 37 | +- Preserve existing membership during editorial reorganization unless evidence warrants a correction. Put fixes without a merged stable backport in the appropriate regular section. |
| 38 | +- Follow the rules' separate stable changelog structure when the requested work includes a stable changelog. Main and stable entries have different placement. |
| 39 | +- Apply the same-cycle regression exclusion from the changelog rules; a fix to an unreleased change normally needs no separate entry. |
| 40 | + |
| 41 | +Group by reader concern: keyboard and screen-reader changes belong in Accessibility; command failures belong under the affected command even if their implementation touched extensions. Sort references within their own repository namespace, keeping external engine references distinct from CLI issue numbers. |
| 42 | + |
| 43 | +Write the user-visible symptom or capability in plain language. Trim mechanisms and repro detail while retaining compatibility consequences, affected formats, options and translation keys needed by users. Verify external credits against contribution history; reused tests or retained commits can justify attribution beyond the final PR author. |
| 44 | + |
| 45 | +For bundled-tool platform requirements, distinguish each binary's requirement from the full product's rendering support. Name whether evidence comes from configuration, documentation, binary inspection or execution. |
| 46 | + |
| 47 | +## Prepare highlights and announcement material |
| 48 | + |
| 49 | +When requested, read [references/website-and-blog.md](references/website-and-blog.md). Select highlights from verified release changes and the previous stable release, including shipped backports. Scale the announcement to the actual release; choose stories because they matter to readers rather than aiming for a fixed number of highlights. |
| 50 | + |
| 51 | +## Verify and hand off |
| 52 | + |
| 53 | +When editing the changelog, check the resulting diff against the baseline: |
| 54 | + |
| 55 | +- Account for every original entry and contributor credit, using counts per reference plus credit so repeated references remain distinguishable. Explain intentional removals. |
| 56 | +- List additions and their landed evidence. Check section hierarchy, reference ordering and any changed Regression fixes membership. |
| 57 | + |
| 58 | +For all content work, run `git diff --check` for tracked edits and parse drafted or edited Markdown with an available Markdown parser. Check documentation links and anchors against the relevant sources; HTTP 200 alone does not establish prerelease content availability. |
| 59 | + |
| 60 | +Report what changed, the evidence, unresolved claims and the exact checks run. Separate content verification from runtime, installer or release-candidate testing. |
| 61 | + |
| 62 | +For work spanning repositories, save the report and requested drafts or handoff prompts in a location supplied by the user or established by repository conventions. If neither exists, choose a review directory in the current workspace and report its location and whether its files are tracked or ignored. Keep reusable guidance in this skill and version-specific facts in the review bundle. |
| 63 | + |
| 64 | +Completion means the requested content is prepared, changes are accounted for, and unresolved publication dependencies are explicit. Commit when requested. Release publication, workflow dispatches and edits in another repository require authority from the user's task; preparing content does not grant that authority. |
0 commit comments