Mirror/brk
1
0
Fork 0
mirror of https://github.com/bitcoinresearchkit/brk.git synced 2026-05-24 00:34:46 -07:00
Code Issues Packages Projects Releases Wiki Activity

changelog: update

Browse Source
This commit is contained in:
nym21
2025-09-20 23:33:39 +02:00
parent 335fe24a54
commit 6554f35710
2 changed files with 800 additions and 553 deletions
Download Patch File Download Diff File Expand all files Collapse all files

298
.claude/prompts/changelog.md
View File

@@ -1,137 +1,221 @@
# Changelog Generation Prompt
# Changelog Generation for Claude Code
Update docs/CHANGELOG.md for ALL latest releases not present in the file. Use ONLY git commands - no other sources.
**TASK**: Update docs/CHANGELOG.md for ALL releases after and including v0.0.107.
## MANDATORY PROCESS - FOLLOW EXACTLY - NO EXCEPTIONS:
1. Run `git tag --list --sort=version:refname` to get releases in order
2. Process EXACTLY ONE release at a time
3. For EACH SINGLE release: run `git diff [previous-tag]..[current-tag]`
4. **MANDATORY ANALYSIS STEP**: Before writing ANY changelog entry, you MUST:
- Analyze each file change and explain what the code is doing
- Identify the purpose and impact of each modification
- Group related changes together logically
- State clearly what functionality is being added, removed, or modified
- If you cannot understand what a change does from the diff, explicitly say so
5. Only AFTER completing the analysis, write the detailed changelog entry
6. Update the CHANGELOG.md file with that ONE entry
7. STOP. Ask me if you should continue to the next release.
## ⚠️ 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**
## CRITICAL CONSTRAINTS:
- **NEVER EVER** process multiple releases in one go, even if there are many
- **NEVER** say "let me continue more efficiently by processing multiple releases"
- **NEVER** batch releases together for any reason
- If you feel tempted to process multiple releases, **STOP** and process only one
- Context window concerns do **NOT** justify batching - process one release only
## CORE WORKFLOW - EXECUTE EXACTLY:
## ABSOLUTE REQUIREMENTS:
- **NEVER** read commit messages, PR descriptions, existing changelog, or any text documentation
- Use **ONLY** the actual code changes shown in git diff output
- Process releases **ONE BY ONE** - I don't care if there are 100 releases
- **MANDATORY**: Before writing changelog entries, demonstrate understanding by analyzing what each code change accomplishes
- Be **HIGHLY DESCRIPTIVE** about what each code change does and why it matters
- Don't be conservative - write detailed explanations of the impact and purpose of changes
- **If you don't understand a change from the code diff alone, DO NOT GUESS - say so explicitly**
### Step 1: Get Release Information
```bash
git tag --list --sort=version:refname
```
## SOURCE OF TRUTH:
- `git diff` output is the **ONLY** source of truth
- If you can't determine what a change does from the code diff alone, say so explicitly
- Ignore **ALL** text/documentation - focus purely on code additions, deletions, and modifications
### Step 2: Process ONE Release at a Time
For each missing release, execute these commands to get complete information:
## CHANGELOG FILE REQUIREMENTS:
- Add a header at the top of the CHANGELOG.md file: `<!-- This changelog was generated by Claude Code -->`
- Ensure this header appears before any changelog entries
**First, get the file list:**
```bash
git diff --name-only [previous-tag]..[current-tag]
```
## CHANGELOG WRITING RULES:
**Then, get changes excluding Cargo.lock:**
```bash
git diff [previous-tag]..[current-tag] -- . ':(exclude)Cargo.lock'
```
### RELEASE TITLE FORMAT:
**MUST** use this exact format: `## [vX.Y.Z](https://github.com/bitcoinresearchkit/brk/releases/tag/vX.Y.Z) - YYYY-MM-DD`
Use the actual release date from git tag information
**If output is too large, examine files individually:**
```bash
git diff [previous-tag]..[current-tag] -- path/to/specific/file.rs
```
### ABSOLUTELY FORBIDDEN PATTERNS:
- **NEVER** mention line counts (e.g., "with 138 lines", "1,290 lines removed")
- **NEVER** use vague action words: "Enhanced", "Improved", "Updated", "Expanded", "Restructured", "Refactored", "Modified", "Adjusted"
- **NEVER** write sections about Cargo.lock or dependency updates unless they represent major functional changes
- **NEVER** use the format "Action: File with vague description"
- **NEVER** mention version bumps of local crates (e.g., "Updated all crate versions from 0.0.61 to 0.0.62") - this is implied by the release version
- **NEVER** mention dependency version changes in external crates unless they enable new functionality visible in the code
- **NEVER** write entries like "Updated dependencies" or "Cargo.lock maintenance"
**For summary of changes per file (if needed):**
```bash
git diff --stat [previous-tag]..[current-tag]
```
### REQUIRED WRITING STYLE:
- Write what the code **actually DOES**, not that it was "enhanced" or "improved"
- Be **specific about functionality**: "Added transaction validation logic", "Implemented caching for API responses"
- Focus on **business/functional impact**: "Enables users to...", "Fixes issue where...", "Adds support for..."
- **Mandatory structure**: Group by: Breaking Changes, New Features, Bug Fixes, Internal Changes
- Include GitHub file links for major changes (max 5 per entry)
- **Skip entirely**: minor dependency bumps, Cargo.lock changes, and local crate version bumps
### Step 3: Analyze Before Writing
**MANDATORY**: Before writing ANY changelog entry, analyze the diff output and explain:
- **Use `git diff --name-only` to 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
### MANDATORY ANALYSIS WORKFLOW:
**BEFORE writing any changelog entry, you MUST:**
**COMPLETENESS CHECK**: State "I have analyzed X files and identified Y distinct functional changes to document"
1. **Code Comprehension Check**: Go through each modified file and explain:
- What specific functionality is being added/removed/changed
- What the new/modified functions/structs/methods do
- How the changes affect the overall system behavior
### Step 4: Write Changelog Entry
Only after analysis, update CHANGELOG.md with ONE release entry.
2. **Impact Assessment**: For each change, determine:
- Is this a new feature, bug fix, breaking change, or internal improvement?
- What user-facing or system behavior changes result from this code?
- What problem does this change solve?
**REQUIRED**: End each release entry with a comparison link:
```markdown
[View changes](https://github.com/bitcoinresearchkit/brk/compare/vPREVIOUS...vCURRENT)
```
Where PREVIOUS is the previous release tag and CURRENT is the current release tag.
3. **Logical Grouping**: Organize related changes together:
- Group files that work together to implement a single feature
- Separate breaking changes from additions
- Distinguish user-facing changes from internal refactoring
### Step 5: Stop and Confirm
**CRITICAL**: Process only ONE release, then ask for confirmation to continue.
4. **Understanding Verification**: Before writing changelog text, state:
- "I understand this change does X because the code shows Y"
- If unclear: "I cannot determine the purpose of this change from the diff alone"
---
**ONLY AFTER completing this analysis should you write the changelog entry.**
## STRICT RULES
### WHAT TO FOCUS ON (IN ORDER OF PRIORITY):
1. **New functionality** - What can users now do that they couldn't before?
2. **Breaking changes** - What existing functionality changed or was removed?
3. **Bug fixes** - What specific problems were resolved?
4. **Internal changes** - New modules, significant refactoring, architecture changes
5. **Skip completely** - Dependency updates, version bumps, Cargo.lock changes
### 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"
### VERBOSITY REQUIREMENTS:
- **Minimum 3-4 bullet points per section** when changes exist
- **Each bullet point should be 1-2 sentences** explaining both what changed and why it matters
- **For new features**: Explain what the feature does and what problem it solves
- **For bug fixes**: Describe the problem that was fixed (inferred from the code changes)
- **For internal changes**: Explain the architectural or structural improvement
### 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**
### EXAMPLES OF GOOD vs BAD:
### 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)
#### ❌ BAD EXAMPLES:
- "Enhanced: Chain analysis with sophisticated blockchain processing capabilities"
- "Updated: brk_rolldown from 0.0.1 to 0.1.0 with comprehensive bundling improvements"
- "Version Bump: Updated all crate versions from 0.0.61 to 0.0.62"
- "Improved error handling"
- "Refactored codebase"
- "Updated dependencies"
## WORKSPACE-SPECIFIC RULES
#### ✅ GOOD EXAMPLES WITH ANALYSIS:
### 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 `workspace` as the crate name
**Analysis**: "Looking at the diff, I see a new `TransactionAnalyzer` struct was added with methods `calculate_fee()` and `is_coinbase()`. The struct takes transaction data and provides analysis methods. This enables users to programmatically analyze transaction properties."
### Cross-Crate Changes:
- **When changes span multiple crates** for one feature, mention the relationship
- **Example**: "Added new transaction API in `brk-core` with corresponding HTTP endpoints in `brk-api`"
**Changelog**: "Added new `TransactionAnalyzer` struct that provides methods for computing transaction fees and detecting coinbase transactions"
### Crate Naming:
- **Use backticks** around crate names: `brk-core`, `brk-api`
- **Use workspace structure** as shown in file paths, not display names
**Analysis**: "The diff shows error handling was added around block parsing where previously there was an unwrap(). Now it returns a Result and handles the empty block case explicitly. This prevents panics when processing malformed blocks."
### File Header (if missing):
```markdown
<!-- This changelog was generated by Claude Code -->
```
**Changelog**: "Fixed panic when processing blocks with zero transactions by adding explicit empty block handling and proper error propagation"
### Release Entry Format:
```markdown
## [vX.Y.Z](https://github.com/bitcoinresearchkit/brk/releases/tag/vX.Y.Z) - YYYY-MM-DD
**Analysis**: "I see a new caching layer was implemented with a HashMap storing block hashes as keys and block data as values. The API endpoints now check this cache before making network requests. This should improve performance for repeated queries."
### Breaking Changes
#### `crate-name`
- Specific change with functional impact explanation ([source](https://github.com/bitcoinresearchkit/brk/blob/vX.Y.Z/path/to/file.rs))
**Changelog**: "Implemented new caching layer for blockchain queries, reducing API response time by storing frequently accessed block data in memory"
### 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
#### ❌ BAD EXAMPLES (NO UNDERSTANDING):
- "Enhanced error handling" (What specific errors? How were they enhanced?)
- "Improved performance" (What was improved? How?)
- "Updated transaction logic" (What specific logic? What changed?)
#### `another-crate`
- Feature specific to this crate
## FINAL REMINDER:
**PROCESS ONLY ONE RELEASE. THEN STOP AND WAIT FOR MY CONFIRMATION.**
### 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
You must be thorough and verbose - if there are code changes, there should be substantial changelog content explaining what those changes accomplish.
### 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:**
1. **File discovery**: "Using git diff --name-only, I see X files were modified"
2. **Cargo.lock check**: "After excluding Cargo.lock, Y files contain actual changes"
3. **Functional changes identified**: "I identified these distinct changes: A, B, C, D..."
4. **What each change does**: "Change A: adds new API endpoints, Change B: fixes memory leak, etc."
5. **Which crates are affected**: "Changes span crates: A, B, C"
6. **What this means for users**: "Users can now do X, bug Y is fixed, etc."
7. **How changes group together**: "Changes A and B work together to implement feature W"
8. **Cross-crate dependencies**: "Crate A's new feature requires the new API in crate B"
9. **Any unclear changes**: "I cannot determine the purpose of change X from the diff"
10. **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):
```markdown
### New Features
- Enhanced blockchain processing capabilities
- Improved error handling and various other updates
```
### ✅ GOOD (Specific, complete, grouped by crate, with source links):
```markdown
### 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.