Skip to main content

🌊 ReleaseWave

AI-Powered Changelog Generator That Actually Works

Reads real code diffs. Works on messy commits. Generates 3 audience-targeted changelogs in one command.

PyPI version Python 3.10+ License: MIT GitHub stars

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:

🚀 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

  1. CLI flags (highest priority)
  2. Environment variables (RWAVE_MODEL, RWAVE_API_KEY)
  3. Config file (.rwave.yml)
  4. Defaults (lowest priority)

🤖 Models

ReleaseWave supports any model via LiteLLM:

Model Provider Cost Quality
gemini/gemini-2.5-flash Google 💚 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      │
└─────────────┘     └──────────────┘       └─────────────┘
  1. Ref Resolution — Validates and resolves git tags/branches/SHAs
  2. Diff Extraction — Runs git diff, filters noise (lockfiles, binaries), respects size limits
  3. Chunking — Splits large diffs into token-safe chunks, grouped by directory
  4. LLM Analysis — Sends diffs + commits to LLM, receives categorized changes
  5. Audience Rendering — Three separate prompts for developer, user, and tweet audiences
  6. 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)

Source distribution for releasewave 1.0.0
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)

Table of built distributions (wheels) for releasewave 1.0.0
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

1.0.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page