8.5 KiB
Changelog Generation for Claude Code
TASK: Update docs/CHANGELOG.md for ALL latest releases missing from the file.
⚠️ CRITICAL FAILURE MODE TO AVOID ⚠️
THE #1 FAILURE: Ignoring most changes and only documenting a few ABSOLUTELY FORBIDDEN: Skipping changes, summarizing with "and other updates", or being incomplete YOU MUST DOCUMENT EVERY SINGLE MEANINGFUL CHANGE - NO EXCEPTIONS
CORE WORKFLOW - EXECUTE EXACTLY:
Step 1: Get Release Information
git tag --list --sort=version:refname
Step 2: Process ONE Release at a Time
For each missing release, execute these commands to get complete information:
First, get the file list:
git diff --name-only [previous-tag]..[current-tag]
Then, get changes excluding Cargo.lock:
git diff [previous-tag]..[current-tag] -- . ':(exclude)Cargo.lock'
If output is too large, examine files individually:
git diff [previous-tag]..[current-tag] -- path/to/specific/file.rs
For summary of changes per file (if needed):
git diff --stat [previous-tag]..[current-tag]
Step 3: Analyze Before Writing
MANDATORY: Before writing ANY changelog entry, analyze the diff output and explain:
- Use
git diff --name-onlyto see ALL changed files - this prevents truncation issues - Use
git diff -- . ':(exclude)Cargo.lock'to see actual changes without Cargo.lock noise - If output is large, examine key files individually with
git diff [tags] -- path/to/file - Identify every functional change - what new capabilities, fixes, or modifications were made
- What each code change accomplishes functionally
- The user-facing or system impact of modifications
- Which crate each change belongs to (based on file paths)
- How changes group together logically within and across crates
- What functionality is added/removed/modified per crate
COMPLETENESS CHECK: State "I have analyzed X files and identified Y distinct functional changes to document"
Step 4: Write Changelog Entry
Only after analysis, update CHANGELOG.md with ONE release entry.
REQUIRED: End each release entry with a comparison link:
[View changes](https://github.com/bitcoinresearchkit/brk/compare/vPREVIOUS...vCURRENT)
Where PREVIOUS is the previous release tag and CURRENT is the current release tag.
Step 5: Stop and Confirm
CRITICAL: Process only ONE release, then ask for confirmation to continue.
STRICT RULES
FORBIDDEN - NEVER MENTION:
- Cargo.lock (ignore completely)
- Line counts ("added 50 lines", "removed 200 lines")
- Dependency version bumps (unless enabling major new features)
- Local crate version changes (0.0.61 → 0.0.62)
- Vague words: "Enhanced", "Improved", "Updated", "Refactored"
FORBIDDEN PHRASES:
- "and other changes"
- "various updates"
- "along with minor improvements"
- "among other enhancements"
- "along with other modifications"
- "plus additional changes"
- "including other updates"
- "and more"
- ANY phrase that suggests you're skipping changes
REQUIRED - MUST INCLUDE:
- Every meaningful change in the diff (no shortcuts)
- Specific functionality descriptions
- Business impact of each change
- Complete coverage - if 20 changes exist, document all 20
- Source links for significant changes (new features, breaking changes, major bug fixes)
WORKSPACE-SPECIFIC RULES
Crate Identification:
- Determine crate from file paths in the diff (e.g.,
crates/brk-core/src/lib.rs→brk-core) - Group all changes by their crate before writing changelog entries
- Use crate name as subheading under each change type section
- For root-level files: Use
workspaceas the crate name
Cross-Crate Changes:
- When changes span multiple crates for one feature, mention the relationship
- Example: "Added new transaction API in
brk-corewith corresponding HTTP endpoints inbrk-api"
Crate Naming:
- Use backticks around crate names:
brk-core,brk-api - Use workspace structure as shown in file paths, not display names
File Header (if missing):
<!-- This changelog was generated by Claude Code -->
Release Entry Format:
## [vX.Y.Z](https://github.com/bitcoinresearchkit/brk/releases/tag/vX.Y.Z) - YYYY-MM-DD
### Breaking Changes
#### `crate-name`
- Specific change with functional impact explanation ([source](https://github.com/bitcoinresearchkit/brk/blob/vX.Y.Z/path/to/file.rs))
### New Features
#### `crate-name`
- Feature description with user benefit ([source](https://github.com/bitcoinresearchkit/brk/blob/vX.Y.Z/path/to/main/file.rs))
- Another feature with implementation details
#### `another-crate`
- Feature specific to this crate
### Bug Fixes
#### `crate-name`
- Specific problem that was resolved ([source](https://github.com/bitcoinresearchkit/brk/blob/vX.Y.Z/path/to/file.rs))
- Another bug fix with impact description
### Internal Changes
#### `crate-name`
- Architectural improvement with purpose
- Code organization change with benefit
[View changes](https://github.com/bitcoinresearchkit/brk/compare/vPREVIOUS...vCURRENT)
ANALYSIS REQUIREMENTS
Before writing changelog text, you MUST state:
- File discovery: "Using git diff --name-only, I see X files were modified"
- Cargo.lock check: "After excluding Cargo.lock, Y files contain actual changes"
- Functional changes identified: "I identified these distinct changes: A, B, C, D..."
- What each change does: "Change A: adds new API endpoints, Change B: fixes memory leak, etc."
- Which crates are affected: "Changes span crates: A, B, C"
- What this means for users: "Users can now do X, bug Y is fixed, etc."
- How changes group together: "Changes A and B work together to implement feature W"
- Cross-crate dependencies: "Crate A's new feature requires the new API in crate B"
- Any unclear changes: "I cannot determine the purpose of change X from the diff"
- FINAL CHECK: "I will now document all X functional changes without listing files"
MANDATORY: The changelog should describe FUNCTIONALITY, not files. But you must capture ALL functionality changes.
Only after this analysis, write the changelog entry.
EXAMPLES
❌ BAD (Vague, incomplete):
### New Features
- Enhanced blockchain processing capabilities
- Improved error handling and various other updates
✅ GOOD (Specific, complete, grouped by crate, with source links):
### New Features
#### `brk-core`
- Added `TransactionAnalyzer` struct with fee calculation and coinbase detection methods ([source](https://github.com/bitcoinresearchkit/brk/blob/v0.0.108/crates/brk-core/src/analyzer.rs))
- Implemented in-memory caching layer for blockchain queries using HashMap storage
#### `brk-api`
- Added three new API endpoints: `/api/blocks/{hash}`, `/api/transactions/search`, and `/api/stats/network` ([source](https://github.com/bitcoinresearchkit/brk/blob/v0.0.108/crates/brk-api/src/routes.rs))
- Implemented standardized error responses with error codes and descriptions
### Bug Fixes
#### `brk-core`
- Fixed panic when processing blocks with zero transactions by adding explicit empty block validation ([source](https://github.com/bitcoinresearchkit/brk/blob/v0.0.108/crates/brk-core/src/block.rs))
#### `brk-api`
- Resolved memory leak in connection pool by implementing proper cleanup in Drop trait
[View changes](https://github.com/bitcoinresearchkit/brk/compare/v0.0.107...v0.0.108)
SUCCESS CRITERIA
✅ COUNT files modified for internal verification only ✅ Identify EVERY distinct functional change ✅ Document ALL functionality changes (no "other changes") ✅ Changelog describes WHAT users can do, not which files changed ✅ Never mention Cargo.lock or line counts ✅ Use specific, functional descriptions ✅ Complete analysis before writing ✅ Stop and ask for confirmation after each release
FAILURE INDICATORS - If you do any of these, you FAILED: ❌ "and other changes" ❌ "various updates" ❌ "among other improvements" ❌ Diff shows new API endpoints but changelog doesn't mention them ❌ Diff shows bug fixes but changelog misses some ❌ Diff shows new structs/functions but changelog ignores them ❌ Missing obvious functional changes from the diff ❌ Summarizing instead of listing each distinct functionality change
KEY PRINCIPLE: Count files internally to ensure you don't miss changes, but write about FUNCTIONALITY for users.