From b5bbae81a6129cf6775349483b8a5d7176b6898b Mon Sep 17 00:00:00 2001 From: Tushar Date: Mon, 13 Apr 2026 15:12:26 +0530 Subject: [PATCH] docs(skills): refine release notes tone guidelines to favor clarity over marketing language --- .forge/skills/write-release-notes/SKILL.md | 27 +++++++++++----------- 1 file changed, 14 insertions(+), 13 deletions(-) diff --git a/.forge/skills/write-release-notes/SKILL.md b/.forge/skills/write-release-notes/SKILL.md index bd5263315f..7bd6617784 100644 --- a/.forge/skills/write-release-notes/SKILL.md +++ b/.forge/skills/write-release-notes/SKILL.md @@ -5,7 +5,7 @@ description: Generate engaging, high-energy release notes for a given version ta # Write Release Notes -Generate compelling, high-energy release notes by pulling live data from GitHub and synthesizing every PR into a cohesive narrative. +Generate clear, informative, and enthusiastic release notes by pulling live data from GitHub and synthesizing every PR into a cohesive narrative. ## Workflow @@ -40,23 +40,23 @@ Dependency bumps (e.g. Dependabot PRs) go into Maintenance. Skip PRs with `error ### 3. Write the Release Notes -Produce a Markdown document with the following structure. Keep the tone **exciting, punchy, and developer-friendly** — celebrate wins, highlight impact, and make readers feel the momentum. +Produce a Markdown document with the following structure. Keep the tone **informative and enthusiastic** — explain what changed and why it matters, without resorting to marketing fluff. ```markdown -# [Product Name] [Version] — [Punchy Tagline] +# [Product Name] [Version] — [Descriptive Tagline] -> One-sentence hook that captures the spirit of this release. +> One-sentence summary of what this release focuses on. ## What's New -[2-4 sentence narrative that weaves together the biggest features and fixes. -Speak to impact, not implementation. Use active voice. Be enthusiastic.] +[2-4 sentence narrative covering the biggest features and fixes. +Describe what changed and what users can now do. Use active voice. Be factual but upbeat.] ## Highlights ### [Feature/Fix Category] -**[PR Title rephrased as user benefit]** -[1-2 sentences expanding on the PR description. Focus on what the user gains. +**[PR Title rephrased as a clear description of the change]** +[1-2 sentences expanding on the PR description. Explain what changed and what users can now do differently. If the PR body has useful context, distill it. If empty, infer from the title.] [Repeat for each significant PR — skip pure chores/dep bumps unless noteworthy] @@ -80,13 +80,14 @@ A huge thank you to everyone who made this release happen: [list @handles — ex ### 4. Tone & Style Guidelines -- **Lead with value**: "You can now..." beats "We added..." -- **Be specific**: Name the feature, not just the category -- **Use energy words**: "blazing", "seamless", "rock-solid", "powerful", "finally" +- **Lead with what changed**: "You can now..." or "Forge now..." beats "We added..." +- **Be specific**: Name the feature and describe what it does, not just the category +- **Be informative, not marketty**: Avoid vague adjectives like "seamless", "smarter", "blazing", "powerful", "rock-solid". Instead, state the concrete fact (e.g. "editor no longer spawns a git process on every keystroke" beats "blazing-fast editor") +- **Enthusiasm through substance**: Let the actual improvement speak for itself. Use active, direct language. - **Short paragraphs**: Max 3 sentences per block - **Skip internal jargon**: Translate crate names and internal concepts into plain language -- **Celebrate contributors**: Name them enthusiastically -- **Tagline formula**: `[Version] — [Adjective] [Theme]` (e.g. "v1.32.0 — Smarter Config, Smoother Workflows") +- **Celebrate contributors**: Name them by handle +- **Tagline formula**: `[Version] — [Factual Theme Description]` (e.g. "v1.32.0 — Terminal Context, File Drop Support, Windows Performance") - **No implementation details**: Do not mention internal module names, struct names, function names, crate names, or how something was implemented. Focus purely on what the user experiences or gains. - **No PR/issue references**: Do not include PR numbers, issue numbers, or links to GitHub PRs/issues in the release notes. Focus on the changes themselves, not their tracking identifiers.