🌊 ReleaseWave
AI-Powered Changelog Generator That Actually Works
Reads real code diffs. Works on messy commits. Generates 3 audience-targeted changelogs in one command.
Quick Start · Why ReleaseWave? · GitHub Action · Configuration · Models
⚡ Quick Start
# Install
pip install releasewave
# Generate changelogs (zero config!)
releasewave generate v1.0.0 v1.1.0
# That's it. Three files appear:
# CHANGELOG-developer.md — Technical changelog
# RELEASE-NOTES.md — User-facing notes
# TWEET.txt — Tweet-sized announcement
🤔 Why ReleaseWave?
Every existing changelog tool has the same fatal flaw: they require clean, conventional commit messages.
Real-world repos look like this:
fix
wip
update stuff
lol this works now
asdfghjkl
merge branch 'main' of github.com/...
ReleaseWave doesn't care. It reads the actual code diffs, not just the commit messages.
| Feature | git-cliff | conventional-changelog | release-please | ReleaseWave |
|---|---|---|---|---|
| Works on messy commits | ❌ | ❌ | ❌ | ✅ |
| Reads actual code diffs | ❌ | ❌ | ❌ | ✅ |
| Multi-audience output | ❌ | ❌ | ❌ | ✅ |
| Zero config | ❌ | ❌ | ❌ | ✅ |
| Monorepo support | ⚠️ | ⚠️ | ⚠️ | ✅ |
| GitHub Action | ❌ | ❌ | ✅ | ✅ |
📋 Three Outputs, One Command
ReleaseWave generates three distinct changelogs per run.
You can view the actual output files generated for this repository in the examples/ directory:
- 🔧 CHANGELOG-developer.md — Technical, precise, with file paths and commit refs.
- 📋 RELEASE-NOTES.md — Plain English, impact-focused, no jargon, made for users.
- 🐦 TWEET.txt — Tweet-sized announcement with highlights.
🚀 GitHub Action
Drop this into your workflow — changelogs generate automatically on every release:
# .github/workflows/release-notes.yml
name: Generate Release Notes
on:
release:
types: [published]
jobs:
changelog:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: Sahaj33-op/releasewave@v1
with:
from_ref: ${{ github.event.release.previous_tag }}
to_ref: ${{ github.event.release.tag_name }}
api_key: ${{ secrets.GEMINI_API_KEY }}
update_changelog: 'true'
See .github/workflows/release-notes.yml for a complete example.
🔧 CLI Reference
# Basic usage
releasewave generate <from_ref> <to_ref>
# Specify model
releasewave generate v1.0 v1.1 --model gpt-4o-mini
# Custom output directory
releasewave generate v1.0 v1.1 --output ./docs/releases
# Only developer + tweet (skip user notes)
releasewave generate v1.0 v1.1 --audiences developer,tweet
# Update existing CHANGELOG.md
releasewave generate v1.0 v1.1 --update-changelog
# Export full analysis as JSON
releasewave generate v1.0 v1.1 --json
# Quiet mode (just write files, no stdout)
releasewave generate v1.0 v1.1 --quiet
# Different repo path
releasewave generate v1.0 v1.1 --repo /path/to/repo
# Initialize config file
releasewave init
# Show recommended models
releasewave models
Alias: You can use rwave instead of releasewave:
rwave generate v1.0 v1.1
⚙️ Configuration
ReleaseWave works with zero configuration, but you can customize everything via .rwave.yml:
# Generate a config file
releasewave init
# .rwave.yml
llm:
model: gemini/gemini-2.5-flash # Any LiteLLM-supported model
temperature: 0.3
max_retries: 3
output:
audiences: [developer, user, tweet]
update_changelog: true
directory: ./docs
filters:
exclude_patterns:
- "*.lock"
- "package-lock.json"
- "node_modules/*"
# Help the LLM understand your project
project_context: "A React dashboard with a FastAPI backend"
custom_prompt: "Pay special attention to API breaking changes"
Configuration Precedence
- CLI flags (highest priority)
- Environment variables (
RWAVE_MODEL,RWAVE_API_KEY) - Config file (
.rwave.yml) - Defaults (lowest priority)
🤖 Models
ReleaseWave supports any model via LiteLLM:
| Model | Provider | Cost | Quality |
|---|---|---|---|
gemini/gemini-2.5-flash |
💚 Very cheap | ⭐⭐⭐⭐ | |
gpt-4o-mini |
OpenAI | 💚 Cheap | ⭐⭐⭐⭐ |
gpt-4o |
OpenAI | 💛 Moderate | ⭐⭐⭐⭐⭐ |
claude-sonnet-4-20250514 |
Anthropic | 💛 Moderate | ⭐⭐⭐⭐⭐ |
ollama/llama3 |
Local | 💚 Free | ⭐⭐⭐ |
openrouter/<model> |
OpenRouter | 💛 Varies | ⭐⭐⭐⭐ |
Set your API key:
# Google Gemini (default, cheapest)
export GEMINI_API_KEY="your-key"
# OpenAI
export OPENAI_API_KEY="your-key"
# Anthropic
export ANTHROPIC_API_KEY="your-key"
# Or use the universal key
export RWAVE_API_KEY="your-key"
# Local Ollama — no key needed!
releasewave generate v1.0 v1.1 --model ollama/llama3
📦 Monorepo Support
ReleaseWave automatically detects monorepo structures and generates per-package changelogs:
my-monorepo/
├── packages/
│ ├── api/ ← Detected as @myapp/api
│ ├── web/ ← Detected as @myapp/web
│ └── shared/ ← Detected as @myapp/shared
├── package.json ← Workspace config
└── .rwave.yml
Supports: npm/yarn/pnpm workspaces, Python packages, Cargo workspaces, Go modules, and more.
🏗️ How It Works
┌──────────────┐ ┌──────────────┐ ┌─────────────┐
│ Git Refs │────▶ │ Diff │────▶│ Chunker │
│ Resolution │ │ Extraction │ │ (Token │
│ │ │ │ │ Safety) │
└──────────────┘ └──────────────┘ └──────┬──────┘
│
┌─────────────┐ ┌──────────────┐ ┌──────▼──────┐
│ 3 Audience │◀────│ LLM │◀──── │ Commit │
│ Changelogs │ │ Analysis │ │ Log + │
│ │ │ │ │ Diffs │
└─────────────┘ └──────────────┘ └─────────────┘
- Ref Resolution — Validates and resolves git tags/branches/SHAs
- Diff Extraction — Runs
git diff, filters noise (lockfiles, binaries), respects size limits - Chunking — Splits large diffs into token-safe chunks, grouped by directory
- LLM Analysis — Sends diffs + commits to LLM, receives categorized changes
- Audience Rendering — Three separate prompts for developer, user, and tweet audiences
- Output — Writes markdown files, optionally updates CHANGELOG.md
🛡️ Edge Cases Handled
- Binary files → Noted as "binary file changed", not sent to LLM
- Massive diffs (1000+ files) → Auto-chunked by directory, merged after analysis
- LLM API failure → Graceful fallback to commit-message-only mode
- No commits in range → Clear error with suggested correct syntax
- Rate limiting → Exponential backoff with configurable retry count
- Lock files & generated code → Excluded by default via filters
🤝 Contributing
Contributions welcome! Here's how to set up the dev environment:
# Clone
git clone https://github.com/Sahaj33-op/releasewave.git
cd releasewave
# Install in dev mode
pip install -e ".[dev]"
# Run tests
pytest
# Lint
ruff check .
# Type check
mypy releasewave/
📄 License
MIT — do whatever you want with it.
Built with ❤️ by Sahaj
If ReleaseWave saves you time, consider giving it a star ⭐
Metadata
Release files for releasewave 1.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| releasewave-1.0.0.tar.gz | 39.6 kB | Without provenance | Details for releasewave-1.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| releasewave-1.0.0-py3-none-any.whl | Python 3 | none | any | Details for releasewave-1.0.0-py3-none-any.whl |
Total release size: 73.1 kB
Release files / releasewave-1.0.0.tar.gz
| Download URL | releasewave-1.0.0.tar.gz |
|---|---|
| Size | 39.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d96248a260212b8b71b9210c24807cc78a0c45c316673abba12e92ceca647904
|
|
BLAKE2b-256 checksum How to use checksums |
5bc58944aa0f16a52846f75f06a5a247a0e96148d0263cabb97851aae6a83b1f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.11
|
Release files / releasewave-1.0.0-py3-none-any.whl
| Download URL | releasewave-1.0.0-py3-none-any.whl |
|---|---|
| Size | 33.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1b2fcc3943d1e69508e108a4866ddaa5e9d3100ce505bc8d49c9861b58143376
|
|
BLAKE2b-256 checksum How to use checksums |
53d7cc48ece48b31f02927ba3e2a81dcb01be94e84b8e9412976e872cb8fa3c2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.11
|
Security for releasewave 1.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.