brose-changelog-cli 1.0.0

AI-powered changelog generator from git commits

brose-changelog-cli

An AI-powered changelog generator that creates structured, user-friendly changelogs from your git history. Built as a developer-friendly tool that simplifies changelog creation and maintenance.

Why This Approach?

I built this tool with two key principles in mind:

1. Developer Experience: The CLI interface makes it seamless to integrate into existing workflows. Developers can generate changelogs with a single command, right where they work - in the terminal.

2. User-Centered Design: The web viewer provides a clean, organized view of changes that end-users care about, similar to Stripe's changelog. Changes are categorized and scored by relevance to ensure the most important updates are highlighted.

Features

• 🤖 AI-powered analysis of git commits
• 📝 Structured changelog generation
• 🌐 Clean, minimal web viewer for changelogs
• 🔍 Smart filtering of relevant changes
• 🎯 Relevance scoring (1-10) to highlight important updates
• 🚫 Automatic exclusion of non-essential files (tests, docs, configs)
• 📊 Weekly organization of changes
• 🏷️ Automatic categorization (Added, Fixed, Changed, Removed)

Installation

uv install brose-changelog-cli

Usage

Generate Changelog

Create or update your changelog based on new git commits:

changelog generate

This will:

• Analyze new commits in your repository
• Generate structured changelog entries
• Create/update changelog/changelog.json
• Generate a formatted CHANGELOG.md

Web Viewer

Launch a clean, minimal web interface to view your changelog:

changelog web

By default, the web viewer runs at http://127.0.0.1:8000. You can customize the host and port:

changelog web --host 0.0.0.0 --port 3000

Configuration

1. Create a .env file:

OPENAI_API_KEY=your-api-key

2. Optionally, set up your OpenAI API key:

export OPENAI_API_KEY=your-api-key

How It Works

1. Commit Analysis: The tool analyzes your git commits, excluding non-essential files like documentation, tests, and configuration files.

2. AI Processing: Each commit is processed through OpenAI's GPT-4 model to:

   • Categorize changes (Added, Fixed, Changed, Removed)
   • Generate user-friendly descriptions
   • Assign relevance scores (1-10)
   • Filter out changes that aren't relevant to end users

3. Changelog Generation: Changes are organized by:

   • Week
   • Commit
   • Change category
   • Relevance (prioritizing high-impact changes)

Technical Choices

• CLI Tool: Built as a command-line tool for seamless integration into developer workflows
• GPT-4: Chosen for its superior understanding of code changes and ability to generate human-friendly descriptions
• Web Interface: Built with FastAPI and React for a responsive, modern changelog viewing experience
• JSON Storage: Structured data storage enables easy updates and flexible rendering

AI Tools Used

• Cursor: Assisted with code completion during development

Requirements

• Python ≥ 3.12
• Git repository
• OpenAI API key

Demo

Loom video showing the tool in action