summarize-releases

Summarize Releases

Turn recent NVIDIA Elements releases into a dated docs page that explains what changed and why users should care. Leave the repository with a focused, validated change that a scheduled agent can propose as a pull request.

Collect the evidence

Run the collector from the repository root. Pass the requested calendar month; otherwise the collector uses the previous calendar month.

mise exec -- node .agents/skills/summarize-releases/scripts/collect-releases.js

The script is the source of truth for:

• the docs page path, URL, title, covered month, publication dates, layout, and collection tags
• release tags and their creation dates
• package names and versions from each tag
• tagged package.json version checks
• the matching section from each tagged CHANGELOG.md
• repeated-commit merging across package changelogs
• conventional commit metadata, messages, and changed-file statistics

The collector only reads the local Git clone. It does not call the GitHub API, query npm, or require a token.

Useful options:

mise exec -- node .agents/skills/summarize-releases/scripts/collect-releases.js --month 2026-07
mise exec -- node .agents/skills/summarize-releases/scripts/collect-releases.js --month 2026-07 --json

Use --include-prereleases only when the user wants preview releases.

For scheduled monthly runs, omit --month to collect the previous calendar month. Pass --month YYYY-MM for historical or explicit reruns. The collector treats the current month as month-to-date and rejects future months.

Check repository freshness

The collector can only report tags available in the clone. When the user requests the latest releases and the clone might be stale or shallow, fetch the public tags before collecting:

git fetch --tags origin

If fetching is unavailable, state that the result covers only the local tags. Do not claim that the report includes the latest releases.

Investigate the changes

Read the complete evidence packet before drafting. Treat changelog text as a lead, not a complete plain-language explanation.

For each potentially user-facing feat, fix, or perf change:

1. Read its full commit message and changed-file list from the packet.
2. Inspect an ambiguous or important diff with git show --stat --patch <sha> --.
3. Check public APIs, component behavior, examples, documentation, and tests to determine the user-visible effect.
4. State only claims supported by that evidence.

Before drafting, make a coverage list of the user-facing changes. For each one, record the user outcome, relevant docs link, whether a short code example would help, and whether to give it a standalone highlight or group it with a closely related change. Do not omit a material feature only because its conventional-commit subject is terse or a larger release includes it.

Changelogs in this monorepo can repeat the same commit across package releases and can mention changes outside the named package. Summarize each unique change once. Do not attribute a change to a package solely because it appears in that package’s changelog; use its scope and changed files.

Give less attention to release automation, CI, dependency bumps, refactors, generated metadata, and test-only work unless it changes installation, compatibility, documentation, performance, or another user workflow. Call out breaking changes and required migration steps first.

Write the docs page

If the packet contains releases, create the file at page.filePath from the packet. The reporting period determines the path and updateMonth; the collector run date supplies the initial publication and modification dates. Do not choose other values.

Before writing, check whether the target already exists. Stop and report the existing page instead of overwriting it unless the user explicitly asks to revise that month. A scheduled rerun must not create a duplicate monthly page.

Use this structure:

---
{
  title: '<page.title from the evidence packet>',
  description: '<one sentence describing the most useful changes>',
  layout: '<page.layout from the evidence packet>',
  tags: <page.tags from the evidence packet>,
  date: '<page.date from the evidence packet>',
  datePublished: '<page.datePublished from the evidence packet>',
  dateModified: '<page.dateModified from the evidence packet>',
  updateMonth: '<page.updateMonth from the evidence packet>'
}
---
 
<One sentence that captures the month’s theme or value.>
 
## Highlights
 
### <Benefit-led heading>
 
<Plain-language explanation with a relevant docs link when available. Combine closely related commits into one coherent change.>
 
```html
<!-- A short, copyable example when the feature has a useful direct API. -->
```
 
## Released packages
 
- `<full package name>` <exact version or compact version range>
 

Apply these rules:

• Write for Elements users, not repository maintainers.
• Explain outcomes and benefits instead of repeating conventional commit subjects.
• Unless the user requests a brief announcement, target a two-to-three-minute read: roughly 350–600 prose words plus short examples and the released-package list. Use two to five thematic highlight sections with enough context to explain why each change matters.
• Include a compact, copyable example for a new component, command, or public API when direct usage helps readers adopt it. Base examples on the changed docs, examples, or source; use fenced html, shell, or js blocks. Do not add an example for a migration, bug fix, or internal change when it would not help a user act.
• Make sure every material user-facing feature from the coverage list appears in a highlight or a related group. Keep the page focused by grouping related improvements rather than silently dropping them.
• Use descriptive link text. Link a new or materially changed component to its docs page when one exists.
• Include each released package once with exact versions. Use a range only when the reporting period includes every version in that range.
• Let the shared What’s New layout render the page title, RSS subscription link, and release-links footer. Do not duplicate them in the Markdown content.
• Keep datePublished fixed after publication. Advance dateModified only when genuinely revising the page content.
• Omit raw commit hashes, internal implementation details, release automation, and empty sections.
• Keep the page useful on its own. Do not mention the scheduled agent, evidence packet, or pull request.
• Do not edit the What’s New index for each run. Its collection lists tagged pages automatically.

If the packet contains no release tags, do not create a page or propose an empty release pull request. Report that the local clone contains no NVIDIA Elements releases for the period. Do not substitute unreleased commits from main unless the user explicitly asks for a preview.

Prepare the copy-ready blurb

After writing the page, return one self-contained block that users can paste into Slack or another channel. Base it on the page, and link its title to page.url when you know the deployed site URL. Do not put it in a code fence.

Use this shape:

✨ What’s new in NVIDIA Elements — <month and year>

<One sentence that captures the month’s theme or value.>

- <Two to five plain-language, benefit-led bullets.>
- <Combine closely related commits into one coherent change.>

Released: <compact package and version list>
Release notes: <https://github.com/NVIDIA/elements/releases>

Keep the blurb roughly 80–180 words unless the user requests another length. Do not repeat detailed research notes unless the user asks for them.

Check the page

Run these checks from the repository root, replacing the placeholder with page.filePath:

mise exec -- vale <page.filePath>
mise exec -- pnpm exec prettier --check <page.filePath>
mise exec -- pnpm --dir projects/site run build
git diff --check

Inspect the built page and the What’s New index when practical. Keep the diff limited to the new monthly page unless another file must change for the page to build correctly.

When the task explicitly requests a pull request, follow the host’s authorized Git publishing workflow only after validation. Otherwise, leave the validated file ready for review and report its path.

Handle incomplete evidence

The collector skips tags whose package version does not match the tag name and reports them as warnings. Investigate skipped tags before drafting, and do not include them unless local evidence proves they represent a package release. Treat missing changelog sections as evidence errors. Use the tag message only when the script marks it as the notes source, and disclose the fallback. If a changelog references a commit that the clone does not contain, fetch more history or disclose the missing evidence. Never invent a summary from an incomplete release title.