|
1 | 1 | --- |
2 | 2 | name: writeReleaseNotes |
3 | | -description: Write release notes for a new version based on git history and previous release notes style. |
4 | | -argument-hint: The new version tag and the previous version tag to diff against (e.g. "v2.0.0-rc.1 since v1.11.2") |
| 3 | +description: Write or update release notes for a new version based on git history and previous release notes style. |
| 4 | +argument-hint: The new version tag and the previous version tag to diff against, or the literal word "update" to refresh an existing in-progress release notes file with new commits since it was last edited (e.g. "v2.0.0-rc.5 since v2.0.0-rc.4", or "update"). |
5 | 5 | --- |
6 | 6 |
|
7 | | -Write release notes for the specified version based on all changes since the specified previous release. |
| 7 | +Write or update release notes for the specified version based on all changes since the specified previous release. |
8 | 8 |
|
9 | | -Follow these steps: |
| 9 | +## Modes |
10 | 10 |
|
11 | | -1. **Study previous release notes** in the `docs/release_notes/` directory to understand the structure, tone, and style used by the project. Pay attention to: |
12 | | - - Header format and date conventions |
13 | | - - How features are grouped and described |
14 | | - - Level of technical detail per feature |
15 | | - - Breaking changes section format |
16 | | - - Contributors section format |
| 11 | +- **Create**: No release notes file exists yet for the version. Build the file from scratch following all steps below. |
| 12 | +- **Update**: Argument is `update` (or the release notes file already exists). Treat the existing file as the source of truth for tone, ordering and editorial decisions, and only ADD entries for commits landed on `origin/trunk` since the file was last edited. Do not rewrite or reorder existing sections unless the user asks explicitly. |
| 13 | + |
| 14 | +To detect update mode and find the relevant commit range: |
| 15 | + |
| 16 | +- Check whether `docs/release_notes/<version>.md` exists. |
| 17 | +- Find when it was last edited: `git log -1 --format='%H' docs/release_notes/<version>.md` |
| 18 | +- New commits to consider: `git fetch origin && git log <last-edit-sha>..origin/trunk --no-merges --format='%h | %an | %s'` |
| 19 | + |
| 20 | +## Steps |
| 21 | + |
| 22 | +1. **Study previous release notes** in `docs/release_notes/` to understand the structure, tone, and style used by the project. Pay attention to: |
| 23 | + - Header format and date conventions (e.g. `# Spice vX.Y.Z (Month D, YYYY)`) |
| 24 | + - Opening summary paragraph that names the release-defining themes |
| 25 | + - Bulleted "Highlights in this release candidate include:" list right under the summary |
| 26 | + - How features are grouped and described (subsections under `## What's New`) |
| 27 | + - Level of technical detail per feature; preferred prose vs. bullets; example YAML snippets |
| 28 | + - Enterprise feature callout style (`> [Spice.ai Enterprise]...` blockquote at the top of the subsection) |
| 29 | + - Breaking Changes section format with migration before/after YAML |
| 30 | + - Contributors section format (GitHub profile links, alphabetised) |
17 | 31 | - Upgrading instructions format |
18 | 32 | - Changelog format with PR links and author attribution |
19 | 33 |
|
20 | 34 | 2. **Gather changes** using `git log` between the two version tags: |
21 | | - - Get all non-merge commits with `git log <prev-tag>..<new-tag> --oneline --no-merges` (or `git log <prev-tag>..HEAD` if the new tag does not exist yet) |
22 | | - - Identify contributors with `git log <prev-tag>..<new-tag> --format="%an <%ae>" --no-merges | sort -u` (or `git log <prev-tag>..HEAD` if the new tag does not exist yet) |
23 | | - - Map contributor names to GitHub usernames by cross-referencing previous release notes and email addresses |
24 | | - - Read commit messages for major PRs to understand feature scope and details |
25 | | - |
26 | | -3. **Categorize changes** into: |
27 | | - - Major new features (deserve their own subsection with description, key points, and examples) |
28 | | - - Dependency upgrades (presented in a table) |
29 | | - - Other improvements (bullet list of smaller features and fixes) |
30 | | - - Breaking changes (with migration guidance) |
31 | | - - Bug fixes (grouped by area) |
32 | | - |
33 | | -4. **Write the release notes** matching the established style: |
34 | | - - Opening summary paragraph highlighting the most important features |
35 | | - - "What's New" section with subsections for each major feature |
36 | | - - Contributors list with GitHub profile links |
37 | | - - Breaking Changes section |
38 | | - - Cookbook Updates section |
39 | | - - Upgrading section with CLI, Homebrew, Docker, Helm, and marketplace instructions |
40 | | - - Changelog section with PR links and author attribution |
41 | | - |
42 | | -5. **Filter noise** from the changelog: exclude CI fixes, test snapshot updates, dependabot bumps, internal refactors, and other non-user-facing changes from the summary sections (but include significant ones in the detailed changelog). |
43 | | - |
44 | | -Save the release notes as a new markdown file in the release notes directory. |
| 35 | + - All non-merge commits: `git log <prev-tag>..<new-tag> --oneline --no-merges` (or `..HEAD` if the new tag does not exist yet; or `<last-edit-sha>..origin/trunk` in update mode). |
| 36 | + - For each non-trivial PR, look up the PR title, body and author on GitHub. Commit subjects often lack the user-facing framing the release notes need. |
| 37 | + - PR metadata: `gh pr view <num> --json title,body,author,labels` |
| 38 | + - Author handle (use this when the commit author name is ambiguous, bot-mangled, or differs from GitHub login): `gh pr view <num> --json author -q '.author.login'` |
| 39 | + - Identify contributors: `git log <range> --format='%an <%ae>' --no-merges | sort -u`, then map each to a GitHub username using `gh pr view` on one of their PRs and by cross-referencing previous release notes. |
| 40 | + |
| 41 | +3. **Filter noise**. Exclude entirely from both the narrative and the changelog: |
| 42 | + - `dependabot[bot]` and `github-actions[bot]` commits unless they update a user-visible dependency (e.g. DuckDB, Iceberg, Turso) — those go in the dependency table. |
| 43 | + - Test/snapshot updates (`fix(tests): ...`, `chore(benchmarks): ...`, `Update snapshots`, `Disable failing ... test in CI`). |
| 44 | + - Internal refactors with no user-visible behaviour change (e.g. lint deny attributes, internal trait reshuffles). |
| 45 | + - Reverts of changes that never shipped in a prior release. |
| 46 | + - `chore: Clean up Cargo.lock`-style housekeeping. |
| 47 | + - Significant internal changes (e.g. CI infrastructure rewrites) MAY be included in the detailed changelog at the bottom but never in the highlights or `## What's New`. |
| 48 | + |
| 49 | +4. **Categorize changes** into: |
| 50 | + - Major new features (deserve their own `### Subsection` with description, key points, and YAML examples when configuration changes). |
| 51 | + - Dependency upgrades (presented in a table at the end of `## What's New`). |
| 52 | + - Smaller improvements (bullet list under broader subsections such as `### SQL, Query, and Developer Experience` or `### Caching & Search`). |
| 53 | + - Breaking changes (with before/after migration guidance). |
| 54 | + - Bug fixes (grouped by area, e.g. `### Connector Bug Fixes`). |
| 55 | + |
| 56 | +5. **Write the release notes** matching the established style: |
| 57 | + - `# Spice v<version> (<Month D, YYYY>)` header followed by a one-paragraph summary naming the headline themes. |
| 58 | + - `Highlights in this release candidate include:` bullet list. |
| 59 | + - `## What's New in v<version>` with subsections for each major feature. |
| 60 | + - `## Contributors` with GitHub profile links, alphabetised case-insensitively. |
| 61 | + - `## Breaking Changes` (omit if none). |
| 62 | + - `## Cookbook Updates` (state "No new cookbook recipes." if none). |
| 63 | + - `## Upgrading` with CLI, Homebrew, Docker, Helm, and AWS Marketplace instructions. |
| 64 | + - `## What's Changed` → `### Changelog` with one bullet per included PR in the form |
| 65 | + `- <title> by [@handle](https://github.com/<handle>) in [#<num>](https://github.com/spiceai/spiceai/pull/<num>)` |
| 66 | + - `**Full Changelog**: <https://github.com/spiceai/spiceai/compare/<prev-tag>...<new-tag>>` |
| 67 | + |
| 68 | +## Ordering |
| 69 | + |
| 70 | +Within both the Highlights bullets and the `## What's New` subsections, **keep the two lists in the same relative order** so the reader can move between them without surprise. |
| 71 | + |
| 72 | +Default thematic order for highlights/subsections, top to bottom: |
| 73 | + |
| 74 | +1. **Spice Cayenne** — always first when there is meaningful Cayenne news. |
| 75 | +2. Security & TLS (mTLS, auth) |
| 76 | +3. CDC sources (MongoDB Change Streams, Kafka offsets, Debezium fixes) |
| 77 | +4. DML / write-back (PostgreSQL, Snowflake, Arrow upserts, DuckLake Beta) |
| 78 | +5. SQL & UDFs (User-Defined Functions, Spatial SQL UDFs) |
| 79 | +6. Runtime features (On-Demand Dataset Loading, SMB client, Unified Cancellation) |
| 80 | +7. HTTP / connector improvements (Dynamic HTTP Connector, HTTP rate-control persistence) |
| 81 | +8. Acceleration (`refresh_mode: snapshot`, new accelerator features) |
| 82 | +9. AI / LLM (Prompt caching, Responses API) |
| 83 | +10. Cross-cutting trailing sections inside `## What's New`: Distributed Cluster Improvements → Caching & Search → Security Improvements → SQL/Developer Experience → Connector Bug Fixes → Dependency Updates. |
| 84 | + |
| 85 | +## Project-specific conventions |
| 86 | + |
| 87 | +- The product surface name is **Spice Cayenne** in narrative prose (highlights, opening paragraph). Inside subsections about Cayenne internals, plain "Cayenne" is fine after the first mention. |
| 88 | +- [@claudespice](https://github.com/claudespice) is a bot and **must not** appear in the `## Contributors` section. It may appear in the `### Changelog` author attribution because that follows the PR's actual author. |
| 89 | +- Use `## What's Changed` then `### Changelog` (not `## Changelog`) to match the GitHub auto-generated layout that prior releases mirror. |
| 90 | +- Verify each PR is referenced at most once in the changelog and at most once in the narrative `## What's New`. Use `grep -c '#<num>' <file>` to spot-check. |
| 91 | +- When updating an existing file, also update the **Contributors** list if the new commits introduce a new author. Skip bots and `claudespice`. |
| 92 | + |
| 93 | +## Documentation links |
| 94 | + |
| 95 | +Link feature names in subsections to the appropriate documentation host. Pick the host based on where the feature is documented, not by audience: |
| 96 | + |
| 97 | +- **OSS / runtime features** → `https://spiceai.org/docs` (e.g. `https://spiceai.org/docs/components/data-connectors/postgres`). |
| 98 | +- **Spice.ai Cloud** → `https://docs.spice.ai/docs` (e.g. `https://docs.spice.ai/docs/api/sql`). |
| 99 | +- **Spice.ai Enterprise** → `https://docs.spice.ai/docs/enterprise` (e.g. `https://docs.spice.ai/docs/enterprise/features/distributed-accelerations`). Enterprise subsections also get the `> [Spice.ai Enterprise](https://docs.spice.ai/docs/enterprise) feature. See [...](<deep-link>).` blockquote at the top. |
| 100 | + |
| 101 | +Verify any new doc link you introduce actually resolves. If a deep link cannot be confirmed, link to the section root instead. |
| 102 | + |
| 103 | +## Output |
| 104 | + |
| 105 | +Save the release notes as `docs/release_notes/v<version>.md`. In update mode, edit the existing file in place and commit with a `docs(release): update v<version> notes with latest trunk PRs` style message. |
0 commit comments