Mirror/brk
1
0
Fork 0
mirror of https://github.com/bitcoinresearchkit/brk.git synced 2026-05-24 08:44: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: ## ⚠️ CRITICAL FAILURE MODE TO AVOID ⚠️
1. Run `git tag --list --sort=version:refname` to get releases in order **THE #1 FAILURE**: Ignoring most changes and only documenting a few
2. Process EXACTLY ONE release at a time **ABSOLUTELY FORBIDDEN**: Skipping changes, summarizing with "and other updates", or being incomplete
3. For EACH SINGLE release: run `git diff [previous-tag]..[current-tag]` **YOU MUST DOCUMENT EVERY SINGLE MEANINGFUL CHANGE - NO EXCEPTIONS**
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 CONSTRAINTS: ## CORE WORKFLOW - EXECUTE EXACTLY:
- **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
## ABSOLUTE REQUIREMENTS: ### Step 1: Get Release Information
- **NEVER** read commit messages, PR descriptions, existing changelog, or any text documentation ```bash
- Use **ONLY** the actual code changes shown in git diff output git tag --list --sort=version:refname
- 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**
## SOURCE OF TRUTH: ### Step 2: Process ONE Release at a Time
- `git diff` output is the **ONLY** source of truth For each missing release, execute these commands to get complete information:
- 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
## CHANGELOG FILE REQUIREMENTS: **First, get the file list:**
- Add a header at the top of the CHANGELOG.md file: `<!-- This changelog was generated by Claude Code -->` ```bash
- Ensure this header appears before any changelog entries 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: **If output is too large, examine files individually:**
**MUST** use this exact format: `## [vX.Y.Z](https://github.com/bitcoinresearchkit/brk/releases/tag/vX.Y.Z) - YYYY-MM-DD` ```bash
Use the actual release date from git tag information git diff [previous-tag]..[current-tag] -- path/to/specific/file.rs
```
### ABSOLUTELY FORBIDDEN PATTERNS: **For summary of changes per file (if needed):**
- **NEVER** mention line counts (e.g., "with 138 lines", "1,290 lines removed") ```bash
- **NEVER** use vague action words: "Enhanced", "Improved", "Updated", "Expanded", "Restructured", "Refactored", "Modified", "Adjusted" git diff --stat [previous-tag]..[current-tag]
- **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"
### REQUIRED WRITING STYLE: ### Step 3: Analyze Before Writing
- Write what the code **actually DOES**, not that it was "enhanced" or "improved" **MANDATORY**: Before writing ANY changelog entry, analyze the diff output and explain:
- Be **specific about functionality**: "Added transaction validation logic", "Implemented caching for API responses" - **Use `git diff --name-only` to see ALL changed files** - this prevents truncation issues
- Focus on **business/functional impact**: "Enables users to...", "Fixes issue where...", "Adds support for..." - **Use `git diff -- . ':(exclude)Cargo.lock'` to see actual changes** without Cargo.lock noise
- **Mandatory structure**: Group by: Breaking Changes, New Features, Bug Fixes, Internal Changes - **If output is large, examine key files individually** with `git diff [tags] -- path/to/file`
- Include GitHub file links for major changes (max 5 per entry) - **Identify every functional change** - what new capabilities, fixes, or modifications were made
- **Skip entirely**: minor dependency bumps, Cargo.lock changes, and local crate version bumps - 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: **COMPLETENESS CHECK**: State "I have analyzed X files and identified Y distinct functional changes to document"
**BEFORE writing any changelog entry, you MUST:**
1. **Code Comprehension Check**: Go through each modified file and explain: ### Step 4: Write Changelog Entry
- What specific functionality is being added/removed/changed Only after analysis, update CHANGELOG.md with ONE release entry.
- What the new/modified functions/structs/methods do
- How the changes affect the overall system behavior
2. **Impact Assessment**: For each change, determine: **REQUIRED**: End each release entry with a comparison link:
- Is this a new feature, bug fix, breaking change, or internal improvement? ```markdown
- What user-facing or system behavior changes result from this code? [View changes](https://github.com/bitcoinresearchkit/brk/compare/vPREVIOUS...vCURRENT)
- What problem does this change solve? ```
Where PREVIOUS is the previous release tag and CURRENT is the current release tag.
3. **Logical Grouping**: Organize related changes together: ### Step 5: Stop and Confirm
- Group files that work together to implement a single feature **CRITICAL**: Process only ONE release, then ask for confirmation to continue.
- Separate breaking changes from additions
- Distinguish user-facing changes from internal refactoring
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): ### FORBIDDEN - NEVER MENTION:
1. **New functionality** - What can users now do that they couldn't before? - **Cargo.lock** (ignore completely)
2. **Breaking changes** - What existing functionality changed or was removed? - **Line counts** ("added 50 lines", "removed 200 lines")
3. **Bug fixes** - What specific problems were resolved? - **Dependency version bumps** (unless enabling major new features)
4. **Internal changes** - New modules, significant refactoring, architecture changes - **Local crate version changes** (0.0.61 → 0.0.62)
5. **Skip completely** - Dependency updates, version bumps, Cargo.lock changes - **Vague words**: "Enhanced", "Improved", "Updated", "Refactored"
### VERBOSITY REQUIREMENTS: ### FORBIDDEN PHRASES:
- **Minimum 3-4 bullet points per section** when changes exist - "and other changes"
- **Each bullet point should be 1-2 sentences** explaining both what changed and why it matters - "various updates"
- **For new features**: Explain what the feature does and what problem it solves - "along with minor improvements"
- **For bug fixes**: Describe the problem that was fixed (inferred from the code changes) - "among other enhancements"
- **For internal changes**: Explain the architectural or structural improvement - **"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: ## WORKSPACE-SPECIFIC RULES
- "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"
#### ✅ 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): #### `another-crate`
- "Enhanced error handling" (What specific errors? How were they enhanced?) - Feature specific to this crate
- "Improved performance" (What was improved? How?)
- "Updated transaction logic" (What specific logic? What changed?)
## FINAL REMINDER: ### Bug Fixes
**PROCESS ONLY ONE RELEASE. THEN STOP AND WAIT FOR MY CONFIRMATION.** #### `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.

1055
docs/CHANGELOG.md
View File

File diff suppressed because it is too large Load Diff