brose-changelog-cli 1.0.0
AI-powered changelog generator from git commits
Requires Python: >=3.12

# 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

```bash
uv install brose-changelog-cli
```

## Usage

### Generate Changelog

Create or update your changelog based on new git commits:

```bash
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:

```bash
changelog web
```

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

```bash
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:
```bash
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](https://www.loom.com/share/52601939e7ec4337a8fd426f8b2e0319?sid=008cf826-20e7-409a-afaa-8e58339db58c)