chore: remove changelog from README, simplify release skill

Alan Shum · claude · Alan Shum · commit bb67bf6de73b · 2026-03-16T12:21:27.000-07:00
Changelog lives in GitHub Releases. Release skill streamlined to
7 steps: version bump, build/test, crates.io, commit, gh release, verify.

Co-Authored-By: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/.claude/skills/release.md b/.claude/skills/release.md
@@ -1,136 +1,71 @@
 # Release semantic-diff
 
-Publish a new version of semantic-diff with consistent versioning across all distribution channels: Cargo.toml, crates.io, GitHub release (with tag), and Homebrew tap.
+Publish a new version to crates.io, GitHub Releases, and Homebrew (via CI).
 
 ## Usage
 
 ```
 /release [version]
 ```
 
-- `version` — optional, e.g. `0.4.0`. If omitted, prompt the user.
+If version is omitted, check current version and ask user.
 
 ## Steps
 
 ### 1. Determine version
 
-If no version argument provided, check current version and ask user:
 ```bash
-cd /Users/kshum/Documents/gitproj/semantic-diff && grep '^version' Cargo.toml
+grep '^version' Cargo.toml
+git tag -l 'v*' | sort -V | tail -3
 ```
 
-### 2. Version consistency check (MANDATORY)
+### 2. Update Cargo.toml
 
-Before making any changes, audit all version sources and report mismatches:
+Edit `version = "..."` to the new version. Run `cargo build` to update Cargo.lock.
 
-```bash
-echo "=== Cargo.toml ===" && grep '^version' Cargo.toml
-echo "=== Git tags (local) ===" && git tag -l 'v*' | sort -V | tail -5
-echo "=== Git tags (remote) ===" && git ls-remote --tags origin 'refs/tags/v*' | awk '{print $2}' | sed 's|refs/tags/||' | sort -V | tail -5
-echo "=== GitHub releases ===" && gh release list --limit 5
-echo "=== crates.io ===" && cargo search semantic-diff --limit 1 2>/dev/null || echo "(unable to check)"
-```
-
-**All of these must align for the target version before the release is considered complete:**
-- `Cargo.toml` version matches `<VERSION>`
-- Git tag `v<VERSION>` exists locally and on remote
-- GitHub release `v<VERSION>` exists with curated notes
-- crates.io has `<VERSION>` published
-- CI workflow triggered (builds binaries + updates Homebrew tap)
-
-If previous releases have mismatches (e.g., GitHub release exists but no git tag, or crates.io is behind), **report them to the user** and offer to fix before proceeding with the new release.
-
-### 3. Update Cargo.toml version
-
-Edit the `version = "..."` line in `Cargo.toml` to the new version. Skip if already correct.
-
-### 4. Add changelog entry to README (MANDATORY — must be in the release commit)
-
-**This step MUST happen before the commit in Step 7.** The changelog is part of the release commit, not a follow-up.
-
-1. Find the previous release tag:
-```bash
-git tag -l 'v*' | sort -V | tail -1
-```
+### 3. Build and test
 
-2. Get all changes since the last tag:
 ```bash
-git log --oneline <previous_tag>..HEAD
-```
-
-3. Read the `## Changelog` section in `README.md` and add a new `### v<VERSION>` entry **above** the previous version.
-
-4. Write human-readable bullet points grouped by theme (features, fixes, perf). Format:
-```markdown
-### v<VERSION>
-
-- **Feature name** — One-sentence description of what it does and why.
-- **Fix** — What was broken and how it's fixed.
+cargo clippy -- -D warnings 2>&1
+cargo build --release 2>&1
+cargo test 2>&1
 ```
 
-5. Also update the config example block in README if any defaults or options changed.
-
-**The README.md changes must be staged along with Cargo.toml in Step 7's commit.**
-
-### 5. Verify the build
-
-```bash
-cd /Users/kshum/Documents/gitproj/semantic-diff && cargo build --release 2>&1
-```
+All must pass before proceeding.
 
-### 6. Publish to crates.io
+### 4. Publish to crates.io
 
 ```bash
-cd /Users/kshum/Documents/gitproj/semantic-diff && cargo publish 2>&1
+cargo publish 2>&1
 ```
 
-If this fails with an email verification error, tell the user to verify at https://crates.io/settings/profile.
+If this fails with email verification, tell user to verify at https://crates.io/settings/profile.
 
-### 7. Commit, tag, and push
+### 5. Commit and push
 
-Ensure the active `gh` account is `alankyshum`:
+Ensure `gh` is authenticated as `alankyshum` and remote uses HTTPS:
 ```bash
 gh auth status
-```
-
-If the active account is not `alankyshum`, switch:
-```bash
-gh auth switch --user alankyshum
-```
-
-Ensure the remote uses HTTPS (so `gh` handles auth):
-```bash
 git remote set-url origin https://github.com/alankyshum/semantic-diff.git
 ```
 
-Commit the version bump, changelog, and any config doc updates together in a single release commit:
-```bash
-cd /Users/kshum/Documents/gitproj/semantic-diff && git add Cargo.toml Cargo.lock README.md && git commit -m "chore: release v<VERSION> with changelog"
-```
-
-**Verify README.md is included** — if `git diff --cached README.md` shows no changes, Step 4 was skipped. Go back and add the changelog entry before committing.
-
-Push to main:
+Commit version bump:
 ```bash
-cd /Users/kshum/Documents/gitproj/semantic-diff && git push origin main
+git add Cargo.toml Cargo.lock
+git commit -m "chore: release v<VERSION>"
+git push origin main
 ```
 
-### 8. Create GitHub release with curated changelog
+### 6. Create GitHub release
 
-Write release notes following this format — do NOT use `--generate-notes`:
+Write curated release notes from `git log --oneline <previous_tag>..HEAD`. Group by theme, not raw commits. Do NOT use `--generate-notes`.
 
 ```bash
 gh release create v<VERSION> --title "v<VERSION>" --notes "$(cat <<'EOF'
 ## What's Changed
 
-### <Feature Category 1>
-- Bullet point summarizing change
-
-### <Feature Category 2>
-- Bullet point summarizing change
-
-### Fixes
-- Bullet point for any fixes
+- **Feature** — Description
+- **Fix** — Description
 
 ## Install / Upgrade
 
@@ -145,46 +80,27 @@ EOF
 )"
 ```
 
-Group changes by theme (e.g. "Adaptive Theme", "Docs & Community", "Fixes") rather than listing raw commits. Use `git log --oneline <previous_tag>..v<VERSION>` to see all changes. Write human-readable descriptions, not commit messages.
-
-### 9. Post-release verification (MANDATORY)
-
-After GitHub release is created, verify all channels are consistent:
-
-```bash
-echo "=== Verify tag ===" && git fetch --tags && git tag -l "v<VERSION>"
-echo "=== Verify GitHub release ===" && gh release view "v<VERSION>" --json tagName,name --jq '.tagName + " " + .name'
-echo "=== Verify crates.io ===" && cargo search semantic-diff --limit 1
-echo "=== Verify CI triggered ===" && gh run list --limit 1
-```
-
-If any channel is missing or mismatched, fix it before proceeding.
+This creates the git tag and triggers the release CI workflow which:
+1. Builds `aarch64-apple-darwin` and `x86_64-apple-darwin` binaries
+2. Uploads them to the GitHub release
+3. Auto-updates the Homebrew tap at `alankyshum/homebrew-tap`
 
-### 10. Monitor CI
+### 7. Verify
 
-The release workflow (`.github/workflows/release.yml`) auto-triggers on tag push (created by `gh release create`). It will:
-1. Build `aarch64-apple-darwin` and `x86_64-apple-darwin` binaries
-2. Upload them to the GitHub release
-3. Auto-update the Homebrew tap formula at `alankyshum/homebrew-tap`
-
-Watch the workflow:
 ```bash
-cd /Users/kshum/Documents/gitproj/semantic-diff && gh run list --limit 1
+echo "=== Tag ===" && git tag -l "v<VERSION>"
+echo "=== GitHub release ===" && gh release view "v<VERSION>" --json tagName,name --jq '.tagName + " " + .name'
+echo "=== crates.io ===" && cargo search semantic-diff --limit 1
+echo "=== CI ===" && gh run list --limit 1
 ```
 
-### 11. Report
-
-Print summary with links and verification status:
-- Cargo.toml: `<VERSION>` ✓
-- crates.io: https://crates.io/crates/semantic-diff ✓/✗
-- GitHub release: https://github.com/alankyshum/semantic-diff/releases/tag/v<VERSION> ✓/✗
-- Git tag: `v<VERSION>` ✓/✗
-- CI workflow: ✓/✗ (triggered / completed)
+Report summary:
+- crates.io: https://crates.io/crates/semantic-diff
+- GitHub release: https://github.com/alankyshum/semantic-diff/releases/tag/v<VERSION>
 - Homebrew: `brew install alankyshum/tap/semantic-diff` (updated by CI)
 
 ## Prerequisites
 
 - `cargo login` authenticated with crates.io
 - `gh` CLI authenticated as `alankyshum`
-- Remote URL set to HTTPS (`https://github.com/alankyshum/semantic-diff.git`)
 - `HOMEBREW_TAP_TOKEN` secret set in `alankyshum/semantic-diff` repo
diff --git a/README.md b/README.md
@@ -177,68 +177,6 @@ chmod +x ~/.claude/hooks/refresh-semantic-diff.sh
 5. AI groups the changed hunks by semantic meaning
 6. You see real-time, grouped changes without leaving the terminal
 
-## Changelog
-
-### v0.6.0
-
-- **Untracked file support** — New (untracked) files are now discovered via `git ls-files --others --exclude-standard` and displayed alongside tracked changes. Shown with `[untracked]` badge in the diff view and `[U]` in the sidebar. Binary detection, 1MB size cap, and path traversal validation included.
-- **Smart path abbreviation** — Long file paths in the sidebar are automatically abbreviated to fit (e.g. `src/app/components/sales-assistant/routes.ts` → `s/a/c/s-a/routes.ts`). Filenames are always kept intact; only parent directories are shortened.
-- **Structural sampling for LLM** — Untracked files use head/mid/tail sampling (4 lines from each region) instead of showing just the first 4 lines, giving the LLM a better view of the file's purpose for grouping.
-- **Fast model defaults** — Default LLM model changed from `sonnet` to `haiku` (Claude) / `gemini-flash` (Copilot) for faster grouping. The classification task works well with fast models. Users can upgrade via `~/.config/semantic-diff.json`.
-
-### v0.5.1
-
-- **Fix** — Show only group-relevant hunks when selecting a file in the sidebar, instead of showing all hunks for that file.
-
-### v0.5.0
-
-- **Drop-in `git diff` replacement** — Use `semantic-diff` as a direct replacement for `git diff` with the same CLI arguments (`--staged`, `--cached`, revision ranges, path filters). Configure as `git config diff.external` for seamless integration.
-- **Incremental grouping** — Files are grouped progressively as LLM responses stream in, so you see organized results immediately instead of waiting for all files to be analyzed.
-- **Clippy lint fixes** — Clean up uninlined format args and `ptr_arg` warnings.
-
-### v0.4.0
-
-- **Adaptive dark/light theme** — Auto-detects terminal background color via OSC 11 protocol (supports iTerm2, Ghostty, kitty, WezTerm, Alacritty, xterm, VS Code terminal). Falls back to `COLORFGBG` env var. Override with `"theme": "dark"` or `"light"` in config.
-- **Light theme** — Full light-background palette with pastel diff colors, dark text, and blue accents for readability on white/light terminals.
-- **Terminal detection guards** — Skips background detection in CI, piped stdin, and `TERM=dumb` environments for zero startup overhead.
-
-### v0.3.0
-
-- **Security hardening** — Secure PID file management with atomic writes and ownership validation, path traversal protection in diff parser and config/cache paths, bounded LLM response reading with validated deserialization, UTF-8 safe truncation.
-- **Stdin-piped LLM invocation** — Prompts sent via stdin instead of command-line arguments to prevent process table exposure.
-- **Secure log file location** — Log file moved to a secure directory with restricted permissions.
-- **Integration test suite** — Added diff rendering, SIGUSR1 signal handling, large diff stress tests, and LLM integration tests.
-
-### v0.2.3
-
-- **Fix** — Resolve clippy warnings in config and LLM modules.
-
-### v0.2.2
-
-- **Fix** — Account for line wrapping in scroll offset calculation.
-- **Badges** — Added crates.io and Homebrew version badges to README.
-
-### v0.2.1
-
-- **Fix** — Remove non-functional cmux resize-pane call from hook.
-- **Docs** — Embed demo video in README.
-
-### v0.2.0
-
-- **Hunk-level semantic grouping** — Groups related hunks across files by intent, matching GitHub Copilot's content-level approach. A single file's hunks can appear in different groups.
-- **Multi-backend AI support** — Added GitHub Copilot CLI (`copilot --yolo`) as a fallback when Claude CLI is not available.
-- **Configuration file** — `~/.config/semantic-diff.json` with JSONC comment support. Configure preferred AI backend, model per backend, with intelligent cross-backend model mapping (e.g. `gemini-flash` → `haiku`).
-- **Grouping cache** — Results cached in `.git/semantic-diff-cache.json` keyed by diff hash. Instant startup when diff hasn't changed.
-- **Group-aware diff filtering** — Selecting a file in the sidebar filters the diff to its entire group. Selecting a group header toggles the filter.
-- **Help overlay** — Press `?` to see all keybindings in a centered popup.
-- **Text wrapping** — Long diff lines wrap with the terminal width instead of being truncated.
-- **Improved key responsiveness** — Accept `Repeat` key events on macOS for smooth held-key navigation.
-- **Scroll-to-top on file select** — File header pinned to top of viewport when selected from sidebar.
-
-### v0.1.0
-
-- Initial release with file-level semantic grouping, syntax highlighting, collapse/expand, file tree sidebar, and Claude Code hook integration.
-
 ## Requirements
 
 - Rust 1.75+
