Blog

## The hidden cost of silent shipping Every time you ship a feature without telling anyone, you are leaving engagement on the table. We analyzed changelog data from 200+ SaaS products and found a consistent pattern: - Products with public changelogs see **23% higher feature adoption** within 30 days of release - Support tickets about "how do I..." drop by **17%** when changes are documented - Users who subscribe to changelog notifications have **2.1x higher retention** at month 6 ## Why most teams skip it The number one reason developers give for not maintaining a changelog: "I don't have time." A typical release cycle already involves writing code, reviewing PRs, testing, and deploying. Adding "write release notes" to the checklist feels like overhead. But here's the thing: **you're already writing the raw material**. Every commit message, every PR description, every issue closed — that's your changelog. It's just in the wrong format. ## From raw commits to polished prose CommitFlow reads your Git history and uses AI to transform it: `fix: resolve session timeout on Safari` → "**Fixed**: Authentication timeout on Safari now properly extends sessions" `feat: add dark mode support with system preference detection` → "**New**: Dark mode with automatic theme switching based on your OS settings" The AI handles: - Filtering out noise (merge commits, chore tasks, WIP commits) - Grouping related changes into logical categories - Writing human-readable descriptions - Detecting breaking changes and security fixes ## Getting started in 5 minutes 1. Connect your GitHub repository 2. CommitFlow starts watching for pushes 3. Your first AI-generated changelog appears automatically 4. Customize the look, add your domain, and share No manual writing. No copy-paste from commit logs. Your users get the updates they deserve, and you get back the hours you'd spend writing them.

## Your changelog is not your commit log The most common mistake: copying commit messages into a list and calling it a changelog. ``` v2.3.0 - fix: resolve race condition in websocket reconnect - refactor: extract auth middleware - chore: update dependencies ``` This tells your users nothing useful. It tells them you shipped confusing internal details. A good changelog entry answers three questions: 1. **What changed?** (user-facing, not technical) 2. **Why does it matter?** (the benefit, not the implementation) 3. **What should I do?** (if any action is needed) ## The formula ``` [Category] [Title] [One sentence summary of what changed and why] [Optional: screenshot, GIF, or before/after] [Optional: "Learn more" link to docs] ``` ## Categories that work Stick to 4 categories. More than that and users stop reading: - **New** — Features, integrations, capabilities - **Improved** — Better performance, cleaner UI, smoother flows - **Fixed** — Bugs resolved - **Deprecated** — Features being removed (with migration path) ## Real examples **Bad:** > Updated the authentication module to use JWT tokens with refresh rotation strategy **Good:** > **Improved** Login is now faster and stays logged in longer > We updated our authentication system so you won't be logged out unexpectedly. Sessions now last 30 days instead of 24 hours. **Bad:** > feat: implemented rate limiting middleware with token bucket algorithm **Good:** > **New** API rate limits help keep things fair > We added rate limiting to our API to ensure consistent performance for everyone. Free tier: 100 req/hr. Pro tier: 1000 req/hr. You will see rate limit headers in responses. ## Automating this The best release notes are the ones that actually get published. That's why we built CommitFlow to do this automatically: 1. GitHub webhook detects new commits 2. AI reads the commits and generates a draft 3. You review and hit publish 4. Users get notified via email, Slack, your in-app widget, and RSS The entire process takes under 60 seconds of human time. The AI learns your voice over time, getting better with every release.

## The architecture CommitFlow is open source (MIT). Here's how the pipeline works under the hood. ``` Git Push → GitHub Webhook → CommitFlow API ├── Filter & Deduplicate ├── AI Generation (Claude) ├── Draft Entry Created ├── Publish (manual or scheduled) └── Distribute ├── Changelog Page ├── Widget (Shadow DOM) ├── Email (Resend) ├── Slack Webhook ├── Discord Webhook └── RSS Feed ``` ## Step 1: Webhook handler The `POST /api/webhook/github` endpoint receives push events. It: - Verifies the HMAC-SHA256 signature - Parses commit metadata (message, author, SHA) - Deduplicates against existing entries - Saves raw commits, returns 200 immediately (GitHub's timeout is 2 seconds) ## Step 2: AI filtering and generation The `lib/ai/filter` module handles: - **Noise filtering**: Removes merge commits, chore tasks, dependabot updates, WIP commits - **Grouping**: Detects related commits (same file, same feature area) - **Prompt engineering**: Builds a structured prompt with commit context, product vocabulary, and voice guidelines - **Generation**: Calls Claude API to produce the formatted entry ## Step 3: Distribution The `POST /api/distribute` endpoint sends updates in parallel: - **Widget**: In-app notification via the embeddable widget - **Email**: Resend API with HTML templates - **Slack/Discord**: Webhook with formatted message blocks - **RSS**: Auto-generated feed at /[slug]/feed.xml ## Widget deep dive The widget (`/api/widget.js`) uses Shadow DOM to isolate styles: ```html <script src="https://commitflow.org/api/widget.js" data-workspace="your-slug" data-color="#6366f1" data-position="bottom-right"> </script> ``` One line of code. No dependencies. Works on any website. The widget: - Creates a Shadow DOM root (no style conflicts) - Fetches recent entries from the public API - Tracks read/unread state in localStorage - Shows a pulsing indicator for new updates - Renders entries inline with category badges ## MCP server For AI agents (Cursor, Claude Code), CommitFlow exposes an MCP server: ```json { "mcpServers": { "commitflow": { "url": "https://commitflow.org/api/mcp/sse", "headers": { "x-api-key": "cflow_..." } } } } ``` Available tools: `list_entries`, `create_entry`, `update_entry`, `publish_entry`, `list_feedback`, `update_feedback_status`, `get_stats`, `list_subscribers` Your AI coding agent can now manage your changelog while you focus on building. ## Running your own The entire codebase is at [github.com/cosmoslife/commitflow](https://github.com/cosmoslife/commitflow). Clone it, set up Supabase + Resend + Anthropic API, and you're running your own instance in 10 minutes.