spirit-release-notes

name	spirit:release-notes
description	Generate human-readable Slack Canvas release notes for Spirit Design System. Use when the user asks to write, create, or generate release notes after a publish.

Release Notes Generator

Generate a Slack-ready release notes document from the latest lerna publish, including a narrative summary, per-package changelog sections, notable omission warnings, and a "What's Next" section pulled from Jira.

Principles

• Human tone, not a changelog dump. The summary paragraph should read like a newsletter, not a list of commit messages.
• Only Features and Bug Fixes in the package sections. Other sections are noise for consumers.
• Warn, don't silently drop. Flag anything potentially important that was filtered out.
• Slack Canvas format. Use Unicode emoji directly (not :emoji: codes). Use # for the document title, ## for top-level sections, ### for subsections (Features, Bug Fixes) — Canvas renders these as proper headers when pasted. Emoji mapping: 📢 loudspeaker, 🚀 rocket, 🎉 tada, 📦 package, 🔮 crystal ball, 🎯 dart, 💬 slack, 🐙 github.

---

Workflow

Step 1 — Identify the Latest Release

git log --format="%as %h%d %s" --tags --simplify-by-decoration | head -5

Find the most recent commit tagged as a release (tagged by lerna, commit message chore(release): publish). Note the date from the first column (YYYY-MM-DD) — this is the release date for the document title.

---

Step 2 — Collect Changelog Data Per Package

For each of the 6 public packages, read the CHANGELOG.md and extract only the latest version section — the content between the first ## [X.Y.Z] header and the second one:

Package display name	npm package	CHANGELOG path
Web React	@alma-oss/spirit-web-react	packages/web-react/CHANGELOG.md
Web	@alma-oss/spirit-web	packages/web/CHANGELOG.md
Design Tokens	@alma-oss/spirit-design-tokens	packages/design-tokens/CHANGELOG.md
Icons	@alma-oss/spirit-icons	packages/icons/CHANGELOG.md
Codemods	@alma-oss/spirit-codemods	packages/codemods/CHANGELOG.md
Analytics	@alma-oss/spirit-analytics	packages/analytics/CHANGELOG.md

Skip a package if its latest version section body contains only Version bump only for package — it had no real changes and should not appear in the release notes.

The GitHub compare URL is embedded in the ## [X.Y.Z](url) header — extract it for the "Full changelog" link.

---

Step 3 — Filter Sections and Collect Entries

From each package's latest section, keep only Features and Bug Fixes. Drop Documentation, Chores, Styles, Code Refactoring, Tests, Dependencies, Reverts (unless they qualify for the warning below).

For each kept entry:

• Strip the scope prefix (**web-react:**, **web:**, etc.) — keep only the description text.
• Keep the #DS-XXXX ticket reference.
• Keep the commit hash as a markdown link: ([abcdef1](https://github.com/alma-oss/spirit-design-system/commit/<full-hash>)) — use the 7-char short hash as display text and the full hash (from the CHANGELOG entry) as the URL.
• Wrap every component name (PascalCase, e.g. Picker, ControlButton, UNSTABLE_File) and every hook/utility name (camelCase with use prefix or similar, e.g. useSelectionState) in backticks.
• Wrap every prop name or HTML attribute name (e.g. elementType, name) in bold instead of backticks.
• Package names (e.g. @alma-oss/spirit-web-react) are always in backticks — including in the package header line.
• Normalize common acronyms when copying from CHANGELOG: css → CSS, html → HTML, etc.

---

Step 3b — Warn About Notable Omissions

Before writing the file, scan the dropped sections for anything a developer should review before publishing. Flag entries matching these criteria:

• Any entry under BREAKING CHANGES
• Any Code Refactoring entry that mentions a component name, prop name, or public export
• Any Reverts of a feature that appeared in a previous release
• Any Dependencies bump that changes a peer dependency consumers declare

Print warnings to the terminal (not in the output file), one line each:

⚠️  Possible omissions — review before publishing:
  [web-react] BREAKING CHANGES: remove deprecated `isDisabled` prop from Button
  [web] Code Refactoring: rename UNSTABLE_Attachment → UNSTABLE_File

If there are no warnings, print: ✅ No notable omissions detected.

---

Step 4 — Build Per-Package Blocks

Format each included package as:

📦 **{Display Name} _{version}_** `{npm-package-name}`

### Features

- {description} {#DS-XXXX} ([{commithash}](https://github.com/alma-oss/spirit-design-system/commit/{full-hash}))

### Bug Fixes

- {description} ([{commithash}](https://github.com/alma-oss/spirit-design-system/commit/{full-hash}))

[Full changelog]({github-compare-url})

Where:

• {Display Name} is the human name (e.g. "Web React", "Design Tokens")
• {version} is the version number (e.g. 4.5.0)
• {npm-package-name} is the full scoped name (e.g. @alma-oss/spirit-web-react)
• The "Full changelog" line must use markdown link syntax [Full changelog](url) — bare URLs containing @ (from scoped package names) break in Slack Canvas because @ is interpreted as a mention
• Omit the Features or Bug Fixes section entirely if there are no entries for it

---

Step 5 — Synthesize the General Changes Summary

Write 1–2 short paragraphs (not a list, not a single block of text) that summarize the release. For smaller releases, one paragraph (~3 sentences) is enough. Each paragraph covers one theme — e.g. new components, feature flags or breaking changes. Use a blank line between paragraphs when there are two.

• What was the overarching theme or focus?
• What are the 1–2 most impactful additions for consumers?
• If any UNSTABLE components were introduced or stabilized, mention it.
• If there are breaking changes or security improvements, call them out as a separate sentence or short paragraph — do not bury them.
• Omit internal migrations (px→rem, refactors) from the narrative — they belong in the package changelog, not the newsletter summary.
• Do not split by framework — avoid phrases like "vanilla web", "vanilla side", or "both React and web"; describe features uniformly.

Tone of voice:

• Use direct "we/you" address: "We've expanded…", "You can now…"
• Lead with what the release enables, not what was technically done: "makes it easier to manage responsive visibility" not "introduces Hidden component"
• Mention new props by name with backticks and explain what they unlock: "control vertical alignment in Card via the new alignmentY prop"
• Feature-flagged additions: "letting teams opt in early without breaking existing behavior"
• Enthusiastic but not marketing-speak — short exclamations are fine, superlatives are not

Do not restate every entry. Write for a developer who reads Slack and wants to know if this release matters to them.

---

Step 6 — Fetch "What's Next" From Jira

Use the Jira MCP to find upcoming work:

1. jira_get_agile_boards — find the board for project key DS
2. jira_get_sprints_from_board — get the active sprint and the next sprint(s) (look for state active and future)
3. jira_get_sprint_issues — for each relevant sprint, fetch issues

From the issues, select only items that represent user-visible new features or components (new components, new props/variants, stabilization of UNSTABLE components). Skip infrastructure, testing, documentation, and tooling work.

Format as a bulleted list:

- **{Component or Feature Name}**
  {One sentence describing what it is and why it matters to consumers.}

If no suitable items are found, write: * More improvements are in the works — stay tuned!

---

Step 7 — Assemble the Full Document

Use this exact structure with Unicode emoji:

# {YYYY-MM-DD} Spirit Design System Release Notes

📢 🚀 🎉 Ahoy, we have a new release with features and improvements. Here we go.

## General Changes

{2–4 sentence summary paragraph}

## News in Packages

{package blocks, with ` ` on a line by itself before each package emoji to force a visible empty line in Slack Canvas}

## What's Next 🔮

{bulleted Jira items}

🎯 You can see more of our [quarterly targets outlook in Notion](https://www.notion.so/almacareer/Spirit-DS-team-Quarterly-Goals-878e92d5b74543039e513c0160fb9117).

## We'd Love to Hear Your Feedback

💬 If you have any ideas, suggestions, or requests regarding the newly introduced unstable components, or if you just need help or want to report a bug or wrong behavior, please get in touch with us on our Slack channel: [#spirit-design-system-support_cs_en](https://slack.com/archives/C068XPSDWQN).

 

🐙 Everything is available in our [repository on GitHub](https://github.com/alma-oss/spirit-design-system/).

 

Thank you for staying with us!

---

Step 8 — Write the Output File

1. Ensure docs/release-notes/ directory exists (create it if not).
2. Write the document to docs/release-notes/{YYYY-MM-DD}.md (same date as the document title; see docs/release-notes/2026-04-13.md for naming).
3. Print the full file path to the terminal.
4. Remind the user to review the ⚠️ warnings (if any) before pasting into Slack Canvas.
5. Commit the file to the repository so it is published under docs/release-notes.

---

Output Example (Abbreviated)

# 2026-04-13 Spirit Design System Release Notes

📢 🚀 🎉 Ahoy, we have a new release with features and improvements. Here we go.

## General Changes

This release brings significant expansion to form and file handling capabilities. ...

## News in Packages

📦 **Web React _4.5.0_** `@alma-oss/spirit-web-react`

### Features

- Add FieldDetails component #DS-2454 ([f4d21fc](https://github.com/alma-oss/spirit-design-system/commit/f4d21fc03e846a02768efebb805eab4e0ae2ce28))
- Introduce Picker component #DS-2359 ([9fd982e](https://github.com/alma-oss/spirit-design-system/commit/9fd982e3fd30e22ae71a42c64ae4efbd034712f2))

### Bug Fixes

- Normalize CardLink typings to PolymorphicComponent ([03176fe](https://github.com/alma-oss/spirit-design-system/commit/03176fe0d3a32315d0edf55502ea0fa7cd5875fb))

[Full changelog](https://github.com/alma-oss/spirit-design-system/compare/@alma-oss/spirit-web-react@4.4.2...@alma-oss/spirit-web-react@4.5.0)

...

## What's Next 🔮

- **Interactive Tag**
  A new interactive tag component designed to display selected options in search filters.

🎯 You can see more of our [quarterly targets outlook in Notion](https://www.notion.so/almacareer/Spirit-DS-team-Quarterly-Goals-878e92d5b74543039e513c0160fb9117).

## We'd Love to Hear Your Feedback

💬 If you have any ideas, suggestions, or requests...

🐙 Everything is available in our [repository on GitHub](https://github.com/alma-oss/spirit-design-system/).

Thank you for staying with us!