mirror of
https://github.com/danielmiessler/Fabric.git
synced 2026-01-09 22:38:10 -05:00
cb837bde2d
## CHANGES - Add high-performance Go changelog generator with GraphQL integration - Implement SQLite-based persistent caching for incremental updates - Create one-pass git history walking algorithm with concurrent processing - Add comprehensive CLI with cobra framework and tag-based caching - Integrate AI summarization using Fabric CLI for enhanced output - Support batch PR fetching with GitHub Search API optimization - Add VSCode configuration with spell checking and markdown linting - Include extensive documentation with PRD and README files - Implement commit-PR mapping for lightning-fast git operations - Add content hashing for change detection and cache optimization
4.8 KiB
4.8 KiB
Product Requirements Document: Changelog Generator
Overview
The Changelog Generator is a high-performance Go tool that automatically generates comprehensive changelogs from git history and GitHub pull requests.
Goals
- Performance: Very fast. Efficient enough to be used in CI/CD as part of release process.
- Completeness: Capture ALL commits including unreleased changes
- Efficiency: Minimize API calls through caching and batch operations
- Reliability: Handle errors gracefully with proper Go error handling
- Simplicity: Single binary with no runtime dependencies
Key Features
1. One-Pass Git History Algorithm
- Walk git history once from newest to oldest
- Start with "Unreleased" bucket for all new commits
- Switch buckets when encountering version commits
- No need to calculate ranges between versions
2. Native Library Integration
- go-git: Pure Go git implementation (no git binary required)
- go-github: Official GitHub Go client library
- Benefits: Type safety, better error handling, no subprocess overhead
3. Smart Caching System
- SQLite-based persistent cache
- Stores: versions, commits, PR details, last processed commit
- Enables incremental updates on subsequent runs
- Instant changelog regeneration from cache
4. Concurrent Processing
- Parallel GitHub API calls (up to 10 concurrent)
- Batch PR fetching with deduplication
- Rate limiting awareness
5. Enhanced Output
- "Unreleased" section for commits since last version
- Clean markdown formatting
- Configurable version limiting
- Direct commit tracking (non-PR commits)
Technical Architecture
Module Structure
cmd/generate_changelog/
├── main.go # CLI entry point with cobra
├── internal/
│ ├── git/ # Git operations (go-git)
│ ├── github/ # GitHub API client (go-github)
│ ├── cache/ # SQLite caching layer
│ ├── changelog/ # Core generation logic
│ └── config/ # Configuration management
└── changelog.db # SQLite cache (generated)
Data Flow
- Git walker collects all commits in one pass
- Commits bucketed by version (starting with "Unreleased")
- PR numbers extracted from merge commits
- GitHub API batch-fetches PR details
- Cache stores everything for future runs
- Formatter generates markdown output
Cache Schema
- metadata: Last processed commit SHA
- versions: Version names, dates, commit SHAs
- commits: Full commit details with version associations
- pull_requests: PR details including commits
- Indexes on version and PR number for fast lookups
Features
- Unreleased section: Shows all new commits
- Better caching: SQLite vs JSON, incremental updates
- Smarter deduplication: Removes consecutive duplicate commits
- Direct commit tracking: Shows non-PR commits
Reliability
- No subprocess errors: Direct library usage
- Type safety: Compile-time checking
- Better error handling: Go's explicit error returns
Deployment
- Single binary: No Python/pip/dependencies
- Cross-platform: Compile for any OS/architecture
- No git CLI required: Uses go-git library
Configuration
Environment Variables
GITHUB_TOKEN: GitHub API authentication token
Command Line Flags
--repo, -r: Repository path (default: current directory)--output, -o: Output file (default: stdout)--limit, -l: Version limit (default: all)--version, -v: Target specific version--save-data: Export debug JSON--cache: Cache file location--no-cache: Disable caching--rebuild-cache: Force cache rebuild--token: GitHub token override
Success Metrics
- Performance: Generate full changelog in <5 seconds for fabric repo
- Completeness: 100% commit coverage including unreleased
- Accuracy: Correct PR associations and change extraction
- Reliability: Handle network failures gracefully
- Usability: Simple CLI with sensible defaults
Future Enhancements
- Multiple output formats: JSON, HTML, etc.
- Custom version patterns: Configurable regex
- Change categorization: feat/fix/docs auto-grouping
- Conventional commits: Full support for semantic versioning
- GitLab/Bitbucket: Support other platforms
- Web UI: Interactive changelog browser
- Incremental updates: Update existing CHANGELOG.md file
- Breaking change detection: Highlight breaking changes
Implementation Status
- ✅ Core architecture and modules
- ✅ One-pass git walking algorithm
- ✅ GitHub API integration with concurrency
- ✅ SQLite caching system
- ✅ Changelog formatting and generation
- ✅ CLI with all planned flags
- ✅ Documentation (README and PRD)
Conclusion
This Go implementation provides a modern, efficient, and feature-rich changelog generator.