diff --git a/CHANGELOG.md b/CHANGELOG.md index da84a77..0eaa246 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,11 @@ All notable changes to this project will be documented in this file. +## [1.13.3] - 2026-04-17 + +- feat(github): add release-title prerequisites and preview-aware release strategy guidance +- feat(oss-readiness): add OSS release messaging rubric for titles and opening summaries + ## [1.13.2] - 2026-04-17 - feat(workflow): load rules-discovery across plan, ship, fix, focus, and spec-review diff --git a/github/README.md b/github/README.md index abeea43..87893b7 100644 --- a/github/README.md +++ b/github/README.md @@ -11,6 +11,7 @@ GitHub skill using GitHub CLI (`gh`): repos, issues, pull requests, Actions, rel - PRs: `github/references/pr.md` - Actions: `github/references/actions.md` - Releases: `github/references/release.md` +- Release strategy + naming + preview guidance: `github/references/release-strategy.md` - Advanced API: `github/references/api.md` Release deep dives: @@ -19,6 +20,8 @@ Release deep dives: - Manage: `github/references/release-manage.md` - Assets: `github/references/release-assets.md` +Use `github/references/release-strategy.md` for title quality, dominant-change selection, release-note opening lines, and GitHub preview / OG-image considerations. + ## Requirements - `gh` (GitHub CLI) diff --git a/github/references/release-strategy.md b/github/references/release-strategy.md index 86163b1..3eeaf9d 100644 --- a/github/references/release-strategy.md +++ b/github/references/release-strategy.md @@ -18,6 +18,17 @@ Rules: - Use `--verify-tag` on every `gh release create` - Never skip versions +## Release Title Prerequisites (ENFORCED) + +Before writing a release title, confirm all of these: + +- **Stable scope**: the merged diff is settled; do not title from an outdated PR description +- **Dominant change identified**: pick the main user-facing change, not the most recent internal task +- **Audience identified**: know whether the release is mainly for users, contributors, or operators +- **Title/body alignment**: the first lines of the release notes reinforce the same story as the title +- **Truthfulness**: the title is strong but not inflated beyond what the release actually changed +- **Social-card awareness**: assume the title and opening lines may appear alone on GitHub release cards or preview images + ## Release Title Format (ENFORCED) ``` @@ -25,14 +36,39 @@ vX.Y.Z — {Short Description} ``` Examples: -- `v1.0.0 — Analyze Skill` -- `v1.2.0 — GitHub Skill + Git Docs Expansion` +- `v1.0.0 — Analyze skill` +- `v1.13.1 — Code review, supercharged` +- `v1.14.0 — Portable review specs` + +Weak examples: - `v1.3.1 — GitHub PR Workflow Improvements` +- `v1.3.1 — Updates` +- `v1.3.1 — Misc fixes` Rules: - Use em dash `—` (not `-` or `–`) - Title ≤ 70 characters -- Describe WHAT was added/changed, not HOW +- Lead with the dominant outcome, not the implementation detail +- Be specific enough that the reader can infer what changed in one glance +- Prefer user-facing capability over internal process wording +- Avoid filler like `updates`, `improvements`, `misc`, `cleanup`, `refactors` +- If two candidates exist, choose the one that better survives being seen without context on a release card + +Practical title heuristic: + +```text +vX.Y.Z — {specific outcome} +``` + +Good: +- `v1.13.1 — Code review, supercharged` +- `v0.8.0 — Faster local inference` +- `v2.4.0 — Rules discovery everywhere` + +Bad: +- `v1.13.1 — Workflow changes` +- `v0.8.0 — Performance updates` +- `v2.4.0 — Internal improvements` ## Release Description Format (ENFORCED) @@ -78,6 +114,22 @@ Every release description MUST follow this exact structure: - Every file listed must have a specific, meaningful description - Group related changes when describing (e.g., "Updated routing table, references section, and output template links") +### Opening Lines / Preview Rules + +Assume the release title plus the opening summary / first bullets may be the only text visible in: + +- GitHub release cards +- Open Graph preview images +- link unfurls in chat tools +- social post screenshots + +Therefore: + +- The opening summary must reinforce the title immediately +- The first bullet should restate the dominant change in concrete terms +- Do not lead with internal maintenance work if the release is mainly about a user-facing capability +- Do not bury the dominant change below less important items + ### Changed Files Detail Level by Bump | Bump | Detail Level | @@ -119,7 +171,10 @@ Follow the enforced format above. No shortcuts. Before publishing, check: - [ ] Title follows `vX.Y.Z — {Description}` format +- [ ] Title is specific, outcome-first, and brief +- [ ] Title matches the dominant user-facing change in the merged diff - [ ] Summary paragraph is present and specific +- [ ] Opening lines reinforce the same story as the title - [ ] Every new file is listed with description - [ ] Every changed file is listed with specific change details - [ ] No vague descriptions ("minor updates", "various fixes") diff --git a/github/references/release.md b/github/references/release.md index d625888..7f05264 100644 --- a/github/references/release.md +++ b/github/references/release.md @@ -2,11 +2,11 @@ Use this section as the entry point for release operations. -**MANDATORY: Read `release-strategy.md` before creating or editing any release.** It defines versioning rules, title format, description format, and the generation protocol. +**MANDATORY: Read `release-strategy.md` before creating or editing any release.** It defines versioning rules, title format, dominant-change selection, description format, preview/OG-card guidance, and the generation protocol. | Intent | Reference | |---|---| -| **strategy / format / versioning** | **`release-strategy.md`** | +| **strategy / format / versioning / title quality / previews** | **`release-strategy.md`** | | create / publish release | `release-create.md` | | list / view / edit / delete release | `release-manage.md` | | upload / download assets, verify attestations | `release-assets.md` | diff --git a/oss-readiness/README.md b/oss-readiness/README.md index 8b650d9..21f8a7b 100644 --- a/oss-readiness/README.md +++ b/oss-readiness/README.md @@ -23,6 +23,7 @@ Use natural language or slash-command shorthand: - `generate llms.txt` - `bump stale version refs in docs` - `check OSS CI readiness` +- `audit release messaging` - `/oss` - `/oss fix` - `/oss llms` @@ -36,6 +37,7 @@ Use natural language or slash-command shorthand: - Repo hygiene: `.gitignore`, changelog, issue/PR templates, topics, description - CI checks: test/lint coverage, optional publish workflow for libraries - Agent instructions: canonical `AGENTS.md` plus optional harness-specific aliases +- Release messaging: title quality, dominant-change selection, and opening-summary quality for public release notes or announcements ## Portability @@ -53,6 +55,7 @@ This skill is designed to work across agent harnesses: - LLM docs generation: `oss-readiness/references/llms-generation.md` - Version sync: `oss-readiness/references/version-sync.md` - CI validation: `oss-readiness/references/ci-validation.md` +- Release messaging: `oss-readiness/references/release-messaging.md` - Scaffold templates: `oss-readiness/templates/` ## Requirements diff --git a/oss-readiness/SKILL.md b/oss-readiness/SKILL.md index e55b7f9..b87ae66 100644 --- a/oss-readiness/SKILL.md +++ b/oss-readiness/SKILL.md @@ -4,7 +4,8 @@ description: | Open-source/public release readiness gate. Audit repos for OSS basics, scaffold missing public-release files, generate llms.txt + llms-full.txt, validate CI, and sync version references. Triggers: "oss", "/oss", "open source readiness", "release readiness", "public release", - "go public", "oss audit", "llms.txt", "generate llms", "version bump docs", "scaffold OSS files". + "go public", "oss audit", "llms.txt", "generate llms", "version bump docs", "scaffold OSS files", + "release title", "release messaging", "release notes", "announcement quality". compatibility: Agent Skills spec (agentskills.io). Works with any agent product that supports SKILL.md frontmatter + Markdown. Optional CLI helpers: git, gh, grep, find, jq, node or python. metadata: version: "0.2" @@ -48,6 +49,7 @@ Use either natural language or shorthand. Route both to the same workflow. | Generate LLM docs | `generate llms.txt`, `/oss llms` | `references/llms-generation.md` | | Sync version refs | `bump stale version refs in docs`, `/oss bump` | `references/version-sync.md` | | Validate CI | `check OSS CI readiness`, `/oss ci` | `references/ci-validation.md` | +| Review release title / notes / announcement framing | `audit release messaging`, `is this a good OSS release title?` | `references/release-messaging.md` | ## Template Variables @@ -211,6 +213,7 @@ Any blocking failure caps grade at C maximum. - [LLMs Generation](references/llms-generation.md) — `llms.txt` + `llms-full.txt` algorithm - [Version Sync](references/version-sync.md) — version detection + doc bumping - [CI Validation](references/ci-validation.md) — CI pipeline rules + starter workflows +- [Release Messaging](references/release-messaging.md) — title, opening-summary, and announcement-quality rubric for public OSS releases ## Templates diff --git a/oss-readiness/references/checklist.md b/oss-readiness/references/checklist.md index 08d0967..08bda39 100644 --- a/oss-readiness/references/checklist.md +++ b/oss-readiness/references/checklist.md @@ -10,6 +10,40 @@ Scaffolded files must stay portable: - Do not hardcode maintainer links, social handles, org names, or inboxes from this skill repository. - Prefer an explicitly provided private security channel. If none exists, leave a placeholder and flag it for maintainer input. +## Optional Release Messaging Checks + +Run these when there is a concrete release draft, release tag, or announcement draft to evaluate. + +These checks are advisory and **not** part of the 23-item OSS basics score unless the user explicitly asks for release-messaging review. + +### 24. Release Title Matches the Dominant Change +- Detection: inspect the latest draft release / release notes / announcement headline +- Pass: + - title is specific + - title is outcome-first + - title is brief + - title reflects the dominant user-facing change + - title is truthful, not inflated +- Fail examples: + - `Updates` + - `Workflow improvements` + - `Internal fixes` +- Fix: rewrite the title around the main external outcome, not the most recent internal task + +### 25. Opening Summary Reinforces the Title +- Detection: inspect the first 1-3 sentences or first bullets of the release notes / announcement +- Pass: + - opening lines reinforce the same story as the title + - the dominant change appears immediately + - vague filler does not lead the announcement + - opening lines are legible out of context in link previews or screenshots +- Fail examples: + - title says `Faster local inference` but opening lines lead with dependency upgrades + - title says `Code review, supercharged` but opening lines lead with generic workflow cleanup +- Fix: reorder and rewrite the opening summary so the dominant change is visible first + +Use `references/release-messaging.md` for the cross-platform rubric. + ## BLOCKING Items (12) For each item, provide: detection command, pass/fail criteria, and fix action. diff --git a/oss-readiness/references/release-messaging.md b/oss-readiness/references/release-messaging.md new file mode 100644 index 0000000..fd52412 --- /dev/null +++ b/oss-readiness/references/release-messaging.md @@ -0,0 +1,102 @@ +# Release Messaging + +Cross-platform rubric for evaluating OSS release titles, release-note openings, and launch-announcement framing. + +Use this when the user asks things like: + +- `is this a good OSS release title?` +- `audit release messaging` +- `improve the release title` +- `rewrite the opening release notes` +- `does this announcement read like a real release?` + +## Core Principle + +The title and opening lines should make the release legible to an outsider in one glance. + +That means: + +- name the dominant user-facing change +- say it in plain language +- avoid internal-only framing +- avoid hype the diff does not support + +## Preconditions + +Before writing a title or lead summary, confirm: + +1. **Stable scope** + - The merged or imminent release diff is known +2. **Dominant change selected** + - One main external change is identified +3. **Audience selected** + - Users, contributors, operators, or developers evaluating the project +4. **Truthfulness check** + - The claim is strong but supported by the release + +## Title Rubric + +A strong OSS release title is: + +- **specific** +- **outcome-first** +- **brief** +- **truthful** +- **aligned with the dominant change** + +Good: + +- `v1.13.1 — Code review, supercharged` +- `v0.8.0 — Faster local inference` +- `v2.4.0 — Rules discovery everywhere` + +Weak: + +- `v1.13.1 — Updates` +- `v0.8.0 — Workflow improvements` +- `v2.4.0 — Internal cleanup` + +## Opening Summary Rubric + +The first 1-3 sentences or first bullets should: + +- reinforce the same story as the title +- surface the dominant change immediately +- avoid leading with maintenance work if the release is really about a feature or capability +- be understandable when quoted in chat previews or screenshots + +Bad pattern: + +```text +v1.13.1 — Code review, supercharged + +This release includes several cleanup items, internal refactors, and minor workflow changes... +``` + +Better pattern: + +```text +v1.13.1 — Code review, supercharged + +This release hardens review in the workflow skill with line-by-line coverage, rule-by-rule enforcement, and fail-closed review output. +``` + +## Anti-Patterns + +Avoid: + +- vague nouns: `updates`, `improvements`, `changes` +- internal-only framing when the release is externally meaningful +- hype words with no evidence +- titles that depend on prior context to make sense +- opening summaries that bury the real release story under housekeeping + +## Fast Evaluation Checklist + +- Can a new reader tell what changed from the title alone? +- Does the title describe the dominant external outcome? +- Do the opening lines reinforce that same outcome? +- Would the title still work if shown alone on a social card? +- Is the wording strong without overselling? + +If any answer is no, rewrite before publishing.