skillshare-changelog

Generate a CHANGELOG.md entry for a release. $ARGUMENTS specifies the tag version (e.g., `v0.16.0`) or omit to auto-detect via `git describe --tags --abbrev=0`. **Scope**: This skill updates `CHANGELOG.md` and syncs the website changelog (`website/src/pages/changelog.md`). It does NOT write code (use `implement-feature`) or update docs (use `update-docs`). ## Workflow ### Step 1: Determine Version Range ```bash # Auto-detect latest tag LATEST_TAG=$(git describe --tags --abbrev=0) # Find previous tag PREV_TAG=$(git describe --tags --abbrev=0 "${LATEST_TAG}^") echo "Generating changelog: $PREV_TAG → $LATEST_TAG" ``` ### Step 2: Collect Commits ```bash git log "${PREV_TAG}..${LATEST_TAG}" --oneline --no-merges ``` ### Step 3: Categorize Changes Group commits by conventional commit type: | Prefix | Category | |--------|----------| | `feat` | New Features | | `fix` | Bug Fixes | | `refactor` | Refactoring | | `docs` | Documentation | | `perf` | Performance | | `test` | Tests | | `chore` | Maintenance | ### Step 4: Read Existing Entries for Style Reference Before writing, read the most recent 2-3 entries in `CHANGELOG.md` to match the established tone and structure. The style evolves over time — always match the latest entries, not a hardcoded template. ### Step 5: Write User-Facing Entry Write from the **user's perspective**. Only include changes users will notice or care about. **Include**: - New features with usage examples (CLI commands, code blocks) - Bug fixes that affected user-visible behavior - Breaking changes (renames, removed flags, scope changes) - Performance improvements users would notice **Exclude**: - Internal test changes (smoke tests, test refactoring) - Implementation details (error propagation, internal structs) - Dev toolchain changes (Makefile cleanup, CI tweaks) - Pure documentation adjustments **Wording guidelines**: - Don't use "first-class", "recommended" for non-default options - Be factual: "Added X" / "Fixed Y" / "Renamed A to B" - Include CLI example when introducing a new feature - Use em-dash (`—`) to separate feature name from description - Group related features under `####` sub-headings when there are 2+ distinct areas ### Step 6: Update CHANGELOG.md Read existing `CHANGELOG.md` and insert new entry at the top, after the header. Match the style of the most recent entries exactly. Structural conventions (based on actual entries): ```markdown ## [X.Y.Z] - YYYY-MM-DD ### New Features #### Feature Area Name - **Feature name** — description with `inline code` for commands and flags ```bash skillshare command --flag # usage example ``` Additional context as sub-bullets or continuation text #### Another Feature Area - **Feature name** — description ### Bug Fixes - Fixed specific user-visible behavior — with context on what changed - Fixed another issue ### Performance - **Improvement name** — description of what got faster ### Breaking Changes - Renamed `old-name` to `new-name` ``` Key style points: - Version numbers use `[X.Y.Z]` without `v` prefix in the heading - Feature bullets use `**bold name** — em-dash description` format - Code blocks use `bash` language tag for CLI examples - Bug fixes describe the symptom, not the implementation - Only include sections that have content (skip empty Performance, Breaking Changes, etc.) ### Step 7: Sync Website Changelog The website has its own changelog page at `website/src/pages/changelog.md`. After updating `CHANGELOG.md`, sync the new entry to the website version. **Differences between the two files**: - Website file has MDX frontmatter (`title`, `description`) and an intro paragraph — preserve these, don't overwrite - Website file has a `---` separator after the intro, before the first version entry - The release entries themselves are identical in content **How to sync**: Read the website changelog, then insert the same new entry after the `---` separator (line after intro paragraph), before the first existing version entry. Do NOT replace the entire file — only insert the new entry block. ### Step 8: RELEASE_NOTES (Maintainer Only) `specs/RELEASE_NOTES_<version>.md` is only generated when the user is the project maintainer (runkids). Contributors skip this step. Check if running as maintainer: ```bash git config user.name # Should match maintainer identity ``` If maintainer: - Read the most recent `specs/RELEASE_NOTES_*.md` as a style reference - Generate `specs/RELEASE_NOTES_<version>.md` (no `v` prefix, e.g. `RELEASE_NOTES_0.17.6.md`) - Structure: - Title: `# skillshare vX.Y.Z Release Notes` - TL;DR section with numbered highlights - One `##` section per feature/fix — describe **what changed** in plain language, with a CLI example or code block if relevant. No "The problem / Solution" structure — just state what it does now - Include migration guide if breaking changes exist **RELEASE_NOTES wording rules** (same user-facing standard as CHANGELOG): - Describe **what changed** from the user's perspective, not how the code changed - **Never mention**: function names, variable names, struct fields, file paths, Go syntax, internal APIs - ✅ Good: "Sync now auto-creates missing target directories and shows what it did" - ❌ Bad: "upgraded `Server.mu` from `sync.Mutex` to `sync.RWMutex` and applied a snapshot pattern across 30 handlers" - Keep it concise — a short paragraph per feature is enough, no need for multi-section breakdowns If not maintainer: - Skip RELEASE_NOTES generation - Only update CHANGELOG.md + website changelog ## Rules - **User perspective** — write for users, not developers - **No fabricated links** — never invent URLs or references - **Verify features exist** — grep source before claiming a feature was added - **No internal noise** — exclude test-only, CI-only, or refactor-only changes - **Conventional format** — follow existing CHANGELOG.md style exactly - **Always sync both** — `CHANGELOG.md` and `website/src/pages/changelog.md` must have identical release entries - **RELEASE_NOTES = maintainer only** — contributors only update CHANGELOG.md + website changelog