| name | release-notes |
| description | Use when preparing public release notes or a release announcement for a new iRaceDeck version. Produces four tailored versions — Discord, Reddit, Elgato Marketplace, and Mirabox Space — from the changelog, the commits/PRs/issues since the previous release, and the actual user-facing value of each change. |
Release Notes
Public-facing release announcements for a new iRaceDeck version. The same release ships four different texts:
| Target | Format | Emoji | Length | Ends with |
|---|
| Discord | Markdown #/## headers, bold, bullets | Discord shortcodes (:checkered_flag:) | No hard limit (keep tight) | Download link + @everyone |
| Reddit | Markdown #/## headers, bold, italic, bullets, [text](url) links | Unicode emoji (🏁 🎥 🎙️) — Reddit does not render :shortcode: | No hard limit | Download link |
| Elgato Marketplace | bold labels, italic, bullets only — no headers, no code backticks, no emoji | none | ≤ 1500 characters | nothing extra |
| Mirabox Space | plain text only — no markdown, no headers, no */**, no backticks, no links | none | keep tight | nothing extra |
Two format rules carry the most weight:
- Discord uses
:shortcode: emoji; Reddit needs actual Unicode emoji characters. A Reddit post pasted with :checkered_flag: shows literal text, not 🏁. Always convert.
- Mirabox Space renders no markdown. Any
*, **, `, #, or [](…) shows as literal characters. The Mirabox version is plain prose with hyphen bullets only.
Process
1. Establish the range and the source of truth
2. Separate user-facing from internal
Release notes describe what a user can see or do differently. Drop everything else. Typical non-user-facing commits to exclude:
docs(...) internal docs/architecture, chore(release: ...) / fix(release: ...) release tooling, ci(...), chore(deps: ...) dependency bumps, internal refactors with no visible effect.
Keep: feat, improve, user-facing fix, and user-visible chore (e.g. a terminology rename users will notice). Maintenance lines are optional and only if notable.
3. Understand what each change really does — read the PRs and the issues
Do not paraphrase commit subjects. For each user-facing change, read the PR body and its linked issue to learn (a) what the user gets, (b) why it matters / what problem it solved, and (c) concrete specifics worth quoting (exact variable names, driver names, behaviors, examples).
gh pr view <pr> --json title,body,closingIssuesReferences,labels
gh issue view <n> --json title,body,labels
Repo numbering gotcha: the squash-merge commit title carries the issue number, not the PR number (e.g. fix(...): … (#733) → issue #733, whose PR is #734). To find the PR from an issue, use the issue's timeline/linked PRs or gh pr list --search "<issue> in:title". Confirm you're reading the right PR before quoting it.
For a large release, delegate this PR/issue research to a subagent that returns a structured per-item report (user value + specifics), so the main context stays focused.
4. Shape the narrative
- Find the release's theme and lead with the headline feature. Group related changes (a new capability + the fixes that hardened it belong together, even across separate PRs).
- Open with a short, racing-flavored lead-in paragraph (Discord/Reddit).
- One user-facing change per bullet, written as a benefit, not a commit subject. Bold the feature/action name.
- Quote concrete specifics that make it real: exact template tokens (
{{focused.car_number}}), the actual new names (Dean, Dylan, Ron, Jakub, Tom), the precise behavior.
- Don't claim "pre-release" for a stable version. Only call it a pre-release if the version carries
-rc/-beta/-alpha.
5. Write all four versions
Start from the Discord version, then derive Reddit (swap emoji to Unicode, drop @everyone), then compress to Marketplace, and adapt that into the plain-text Mirabox Space version.
Footer — Discord & Reddit only
Both announcement posts end by pointing readers at the download page (and nothing else — no cross-promotion to the stores):
**Download:** https://iracedeck.com/downloads/
Add @everyone as the final line only on Discord. The two storefront versions (Elgato Marketplace, Mirabox Space) are product descriptions posted on the store, so they carry no footer link.
The download page is the canonical link: https://iracedeck.com/downloads/.
Section emoji (suggested)
| Theme | Discord shortcode | Reddit Unicode |
|---|
| Title / standings | :checkered_flag: | 🏁 |
| Camera / video / focused | :movie_camera: | 🎥 |
| Telemetry / positions | :bar_chart: | 📊 |
| Race Engineer / voice | :microphone2: | 🎙️ |
| Actions / quality-of-life | :joystick: | 🕹️ |
| Fixes | :bug: | 🐛 |
| Race start | :vertical_traffic_light: | 🚦 |
| Spotter / awareness | :eyes: | 👀 |
Vary the title vs section emoji so the same glyph isn't repeated.
Marketplace version — the 1500-character discipline
- Hard cap 1500 characters. Verify before handing it over:
printf '%s' "$TEXT" | wc -c.
- No
# headers, no ` code backticks, no emoji — Marketplace renders a limited subset. Use bold labels (**New**, **Improved**, **Fixed**), italic for emphasis/variable names, and - bullets.
- Lead with the version name in bold, then the bold-labeled groups. Keep it scannable; drop the lead-in prose and the footer links.
Mirabox Space version — plain text only
The Mirabox (Stream Dock) store description renders no markdown, so anything but plain prose leaks formatting characters into the listing.
- No
# headers, no */** (they print as literal asterisks), no ` backticks, no [text](url) links, no emoji.
- Structure with plain words only: a title line, group labels (
New, Improved, Fixed) each on their own line, and - hyphen bullets (a hyphen is just punctuation — fine in plain text).
- Write variable tokens and quoted names as plain text — e.g.
focused, "Your Name" — not in backticks or italics.
- Same content as the Marketplace version, stripped of all formatting. No footer link.
Reference example
The v1.21.0 Discord post is the canonical style reference. Match its tone (concise, benefit-led, racing-flavored) and its ## :emoji: Section structure. (Its old closing cross-promoted the stores "in a couple of days" — that line is dropped; announcements now end with just the Download link, plus @everyone on Discord.)
Don'ts
- Don't invent or overstate — every claim must trace to a PR/issue.
- Don't list internal churn (CI, deps, release tooling, internal docs).
- Don't repeat a change across "Features" and "Fixes" — collapse a feature and its follow-up fixes into one bullet.
- Don't paste Discord
:shortcode: emoji into the Reddit version.
- Don't exceed 1500 characters on Marketplace.
- Don't put any markdown (
*, **, `, #, links) or emoji in the Mirabox Space version — plain text only.
