Create Release Blog

Create Release Blog

Overview

Draft a bilingual release blog post under website/docs/{en,zh}/blog/ for a given version range. The post is an article, not a changelog: an opening overview, a few in-depth highlight sections, then a single closing sentence linking to the GitHub release page.

The user will polish the draft manually. Aim for a strong starting point — readable prose, real code samples pulled from the actual PRs — not a finished post. The Style guidance section below defines the voice, wording, and formatting conventions to follow.

This is not a GitHub release-note generator. For that, use the create-draft-release-notes skill. Release notes enumerate every commit; release blogs select 3–5 features and tell a story about them.

Workflow

1. Resolve the version range

Accept these input shapes:

• previous_tag..next_tag — explicit two-sided range. Use as-is; skip the range-start prompt below.
• next_version (e.g. 0.10.0) — resolve the range start via the prompt below; the end is HEAD.
• No input — ask the user for the next version first (with gh release list --limit 5 as context), then run the prompt below.

The filename is announcing-<major>-<minor>.mdx (e.g. 0.10.0 → announcing-0-10.mdx).

Prompt for the range start

Run the resolver to compute candidate predecessors:

node .agents/skills/create-release-blog/scripts/resolve-range-start.mjs <next-version>

It prints JSON like:

{
  "nextVersion": "0.10.0",
  "bump": "minor",
  "sameTier": "v0.9.0",
  "latest": "v0.9.10",
  "sameTierEqualsLatest": false,
  "tagPrefix": "v"
}

sameTier is the predecessor in the same bumped tier (previous minor's .0, previous patch, or last tag of the previous major). latest is the most recent tag below nextVersion.

Use AskUserQuestion to pick the range start:

• If sameTierEqualsLatest is false and both are non-null, offer two options:
  1. <sameTier> — labeled e.g. "Previous minor (v0.9.0)" with a description explaining "same biggest-version-tier predecessor; covers the full minor cycle".
  2. <latest> — labeled e.g. "Latest release (v0.9.10)" with a description "most recent published tag; covers only commits since that patch".
• If sameTierEqualsLatest is true, offer one option (<latest>) and rely on the auto-added "Other" entry for a custom tag.
• If either candidate is null, present whichever is non-null plus "Other".

The user picks one option, picks "Other" to type a custom tag, or types one inline.

The resolved range is <chosen-start>..<next-end> where <next-end> is HEAD (or the user's explicit end tag). The start tag is excluded from the search — git's A..B syntax yields commits reachable from B but not from A, so commits on the start tag itself are not included.

State the resolved range and the target filename before continuing.

2. Collect and bucket commits

Run the helper:

node .agents/skills/create-release-blog/scripts/collect-commits.mjs <previous_tag>..<next_tag>

It prints JSON with breaking, feat, fix, perf, refactor, docs, other. Each entry has sha, type, scope, subject, prNumber, raw. Step 3 reads the breaking and feat buckets; the other buckets are produced for completeness but unused by this flow.

3. Order highlight candidates

Sort entries in the breaking + feat buckets so the most blog-worthy ones appear first when you present them. This is ordering, not pruning — all candidates are still presented to the user in the next step.

• breaking entries come first and are pre-recommended as defaults — breaking changes almost always warrant a highlight section.
• Within feat, rank by user-facing significance:
  • Scope priority: core > browser/browser-react/coverage-istanbul > adapter-*/vscode > internal/tooling scopes.
  • PR weight (signal of size): gh pr view <N> --json additions,deletions,files; bigger user-facing diffs outrank tiny ones. Discount lockfiles, generated code, and fixture-only diffs.
  • Docs touched: PRs that modified website/docs/** are user-facing — bump them up.
  • Subject keywords: subjects with "support", "add", "new" beat "tweak", "improve", "expose".

4. Summarize every candidate and ask the user to pick

Read each candidate PR before listing them — do not paste raw commit subjects. For every candidate, fetch the PR:

gh pr view <PR> --json title,body,files,labels

Then write one sentence of user-side value per candidate:

• Lead with the user-visible benefit, not the implementation. Good: "Run only the tests affected by your uncommitted changes for faster local iteration." Bad: "Add a --changed flag wired through the module graph resolver."
• Drop framework-internal jargon (taskContext, birpc, dispatch namespace) unless the feature is itself about that internal — and even then, gloss it ("the worker-to-host channel").
• If the PR body has a clear motivation paragraph, paraphrase it. If the PR body is thin (one-liner, just a checklist), infer the user impact from the files field and the related docs path, and say so explicitly: "PR body was thin; summary inferred from changed files."

Present all candidates as a numbered markdown list — do not use AskUserQuestion, which caps at 4 options per question and is too narrow for this step. Format:

1. **`feat(core): subject`** ([#1234](https://github.com/web-infra-dev/rstest/pull/1234))
   <one-sentence plain-language user-value summary>

2. **`feat(browser): subject`** ([#1235](https://github.com/web-infra-dev/rstest/pull/1235))
   <summary>

...

End with: "Reply with the numbers you'd like to highlight (e.g. 1,3,5). 2–4 is the sweet spot — fewer reads thin, more dilutes the article." Wait for the user's reply before continuing.

5. Gather code-sample context for each chosen highlight

The PR body was already loaded in step 4. For each selected highlight, additionally:

gh pr diff <PR> | head -300        # see the API surface

Then:

• Look for a related docs page in website/docs/en/; if present, link to it from the highlight section instead of restating the docs.
• Extract a small (5–15 line) code sample that shows the new surface. Prefer real code from PR-added tests, examples, or docs. Do not invent API shapes — if the PR diff doesn't show usage, search the test fixtures or website docs for an example.

6. Write the EN post

Path: website/docs/en/blog/announcing-<major>-<minor>.mdx. Structure:

---
description: 'One-line summary used on the blog list and as OG description.'
date: YYYY-MM-DD HH:mm:ss
sidebar: false
authors:
  - name: <github-handle>
    avatar: 'https://github.com/<github-handle>.png'
---

_Month Day, Year_

# Announcing Rstest X.Y

<img
  src="https://assets.rspack.rs/rstest/rstest-banner-vX-Y.png"
  alt="Rstest X.Y"
  style={{
    boxShadow: '0 2px 6px rgba(0, 0, 0, 0.08)',
  }}
/>

Rstest X.Y has been released.

Notable changes:

- <Feature one: short noun- or verb-phrase>
- <Feature two: short noun- or verb-phrase>
- <Feature three: short noun- or verb-phrase>
- <Feature four: short noun- or verb-phrase>

## <Feature one heading>

<2–3 short paragraphs that lead with what shipped, then walk through motivation, mechanism,
and trade-offs. Stay factual, no narrative bridges.>

<Code block introduced by a concrete action verb — see Style guidance.>

<Optional follow-up paragraph ending with a uniform docs link — see Style guidance.>

## <Feature two heading>

...

---

For a full list of changes, see the [vX.Y.Z release notes](https://github.com/web-infra-dev/rstest/releases/tag/vX.Y.Z).

Rules for frontmatter authors:

• List the people who drafted this specific post, not the maintainer set. Without authors, the blog list shows the generic Rstest Team.
• Ask the user who should be credited and in what order; do not infer from git log or PR authorship.
• Each entry takes name (GitHub handle) and avatar (https://github.com/<handle>.png). Keep the order identical between EN and ZH frontmatter.

Rules for the banner image:

• Insert the banner between the H1 and the greeting. Use <img> JSX (not markdown ![alt](url)) so it can carry an inline boxShadow — the shadow separates the lower edge from a white page background in light mode.
• Do not set width / aspectRatio / objectFit. The banner is designed at its intended on-page size; extra constraints crop or shrink the artwork.
• Asset URL: https://assets.rspack.rs/rstest/rstest-banner-v<major>-<minor>.png (no patch segment; blog posts are per-minor). Banners ship via PR against rstackjs/rstack-design-resources.
• Generate the banner and OG card together with pnpm gen:release-image from website/ and compress both with pnpm dlx pngquant-bin before committing them to design-resources. website/AGENTS.md ("Release image generation") owns the exact commands and flags.
• For a local preview before the CDN asset exists, temporarily copy the banner into a public directory under website/docs/ (create it if absent) and point src at /rstest-banner-v<major>-<minor>.png. Revert both before opening the PR.
• Inline style: {{ boxShadow: '0 2px 6px rgba(0, 0, 0, 0.08)' }}. No border, no border-radius.

Rules for the OG image:

• The OG card is a separate asset from the banner: rstest-og-image-v<major>-<minor>.png (2400×1260, 1.91:1 social-share aspect). Do not point og:image at the banner — a wide strip renders poorly as a Twitter/Slack card.
• Per-post override lives in website/rspress.config.ts via the top-level head function (route-aware). Frontmatter head does not override the site-wide default reliably: rspress doesn't dedupe og:image, so two tags end up in the HTML and scrapers pick the first.
• Confirm the OG asset resolves before publish (curl -I).

Rules for the intro:

• Open with a one-line greeting: Rstest X.Y has been released. — period, not exclamation; factual, not celebratory. (See Style guidance for the broader tone rules.)
• Follow with Notable changes: and a bullet list of the chosen highlights. Each bullet is a short noun- or verb-phrase naming the feature, wrapped as a markdown link to that section's \{#kebab-case} anchor. The entire bullet is the link text — do not link only a fragment.
• Bullets carry no PR links, code fences, or extra prose, and no narrative paragraph follows them. The bullets are the overview; the section bodies do the explaining.

Rules for the closing release-notes link:

• Close the post with a single sentence linking to the GitHub release page for this version. No ## More improvements heading, no per-PR bullet list — the release page already enumerates everything.
• Template: For a full list of changes, see the [vX.Y.Z release notes](https://github.com/web-infra-dev/rstest/releases/tag/vX.Y.Z). The URL must use the v-prefixed tag (v0.10.0, not 0.10.0).
• Place it as the last paragraph of the post, immediately after the last highlight section. Do not wrap it in a heading.
• Separate it from the preceding section with a markdown horizontal rule (--- on its own line, blank lines above and below) — it's a meta-pointer, not a continuation.

Do not add an Acknowledgements / "Thanks to contributors" section. The post ends with the release-notes link. Contributors are surfaced on the release page itself.