SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsrelease-notes

release-notes

Writing & research

View repository

Updated 10-29 11:59

About this skill

Produce the full GitHub release body for a new Docus version, based on CHANGELOG.md, into v<version>.md at the repo root. The user edits it and pastes it into the GitHub release. The generator does everything mechanical; you write the Highlights and the New documentation list (the parts that need judgement and verification).

When to run: pnpm release writes the CHANGELOG.md block, tags, pushes and opens a prefilled GitHub release in the browser. Run this skill at that point; the generated body replaces the prefilled one.

Patch releases (x.y.z with z > 0) have no Highlights section. The generator detects this from the version, so for a patch skip step 2.

Steps

1. Generate the scaffold

node .claude/skills/release-notes/scripts/generate.mjs        # newest version in CHANGELOG.md
node .claude/skills/release-notes/scripts/generate.mjs 5.16.0 # a specific version

This reads the version block of CHANGELOG.md and writes v<version>.md with:

  • a ## ✨ Highlights placeholder (yours to fill), minor and major versions only,
  • the Breaking Changes / Features / Bug Fixes / Performance / Reverts sections with emoji headers, copied from the changelog,
  • ## 💚 Contributors: PR authors and commit co-authors (one gh api graphql call), @larbish first then by contribution count,
  • a ## 📚 New documentation placeholder when docs/content/en changed,
  • the **Full Changelog** compare line.

It prints the highlight candidates (Features, Performance and Breaking Changes bullets) and the new documentation candidates (new pages and new ##/### headings). gh must be authenticated (gh auth status).

2. Write the Highlights (minor and major versions only)

Skip this step for a patch release, even when a fix is notable.

Pick 2 to 4 changes, most impactful first. Candidates include Performance: a minor can ship without features (v5.15.0 was all performance work).

Good highlight material:

  • a new capability users turn on or configure (an app.config.ts key, a nuxt.config.ts option, a new component, slot or composable),
  • a broad or cross-cutting change (assistant, MCP, llms.txt and agents, search, SEO, i18n, theming, performance),
  • something that closes a long-standing or popular request.

Skip narrow fixes, docs fixes and internal refactors. For each highlight write:

### 🤖 Short title

One or two sentences on what it does and why it matters, linking the
[guide](https://docus.dev/en/ai/assistant#custom-provider).

```ts [app.config.ts]
// a minimal, real example
```

> [!TIP]
> Optional callout for a caveat or neat detail.

Rules:

  • Verify before you write. Check option names, defaults and components against the merged PR (gh pr view <n> --repo nuxt-content/docus), docs/content/en/**, layer/index.d.ts (nuxt.config options), layer/app/types/index.d.ts and layer/nuxt.schema.ts (app.config), layer/modules/** and layer/app/components/**. Never invent an API.
  • Match the voice: concise, direct, no em dashes, reads like Baptiste wrote it. Look at the last few releases for tone: gh release list --repo nuxt-content/docus --limit 5, then gh release view <tag> --repo nuxt-content/docus.
  • Describe what actually shipped, not what it enables. A title must match the real change. Don't inflate a small option into a big feature (e.g. a vary header on markdown negotiation is a caching fix, not "agent-ready docs").
  • When unsure, prefer fewer, accurate highlights over four.
  • Emojis: 🤖 assistant/MCP/agents, 🏎️ performance, 🔍 search/SEO, 🎨 theming/customization, 🌐 i18n, 🧩 components, ♿ accessibility.

3. Breaking changes and upgrade notes

If there is a ⚠️ Breaking Changes section, or a feature/fix requires users to change their project on upgrade (check the PR description), add a callout with the migration step and a docs link, right below the related section:

> [!WARNING]
> What changed, what to do, and a [link to the docs](https://docus.dev/en/...).

4. Fill New documentation (any release with candidates)

Keep only pages and sections that document something new in this release. Drop headings that were renamed, moved or reworded. Check each anchor against the heading on the page. List them as bare URLs, one per bullet:

## 📚 New documentation

* https://docus.dev/en/ai/assistant#custom-provider

Delete the section if nothing qualifies.

5. Sanity-check and report

  • Confirm the contributor list looks right. Co-authors whose email isn't linked to a GitHub account are missed: git log <prev>..<tag> --pretty=%b | grep -i co-authored-by.
  • Remove any leftover <!-- TODO --> comment.
  • Tell the user the file path, which highlights you chose (minor/major only), and which docs links you kept.
  • Do not commit it. It's a scratch file (ignored by .gitignore) the user pastes into GitHub.

Format notes (kept in sync with past releases)

  • Section order: Highlights → Breaking Changes → Features → Bug Fixes → Performance → Reverts → Contributors → New documentation → Full Changelog.
  • Patch releases skip Highlights and start at the first changelog section.
  • Headers use unicode emojis (## 🚀 Features), not :shortcodes:.
  • Performance Improvements is renamed to Performance.
  • Docs URLs drop numeric prefixes: docs/content/en/4.ai/1.assistant.md → https://docus.dev/en/ai/assistant.