releasesmith

releasesmith is an AI-powered changelog and release-notes generator for Git repositories. One command turns commit history into structured, readable release documentation, with deterministic rule-based parsing and optional LLM enhancement.

• Offline-first: no API key? --no-llm still produces a useful changelog.
• Deterministic-first: rules classify commits; LLM is only an enhancer.
• Safe-by-default: read-only on your repository; atomic output writes.

Features

• Parses Conventional Commits (feat, fix, perf, refactor, docs, build, ci, test, chore), scopes, ! breaking markers and BREAKING CHANGE: footers.
• Extracts PR numbers, closing issue references, co-authors and trailers.
• Two-layer classification: offline rules first, batched validated LLM calls only for what rules cannot resolve (with tenacity retries and a safe deterministic fallback).
• Groups history into per-tag releases plus an Unreleased section with Keep a Changelog-style categories.
• Conservative deduplication — never merges breaking changes or entries with issue/PR references.
• Renderers: Markdown, JSON, self-contained HTML (dark mode, no CDN, no JS required), Twitter/X thread drafts.
• Optional LLM polish rewrites entry wording in batches without touching hashes, refs or technical facts.
• English (en) and Traditional Chinese (zh-TW) headings and UI strings.
• Local FastAPI web UI sharing the exact core pipeline with the CLI.
• Typer CLI with Rich panels: every error explains what, why and how to fix — without leaking secrets.

Supported LLM providers

No key configured? Everything still works with --no-llm.

Installation

# uv tool
uv tool install releasesmith

# pipx
pipx install releasesmith

# from source
git clone https://github.com/JToSound/releasesmith
cd releasesmith
uv sync --all-groups
uv run releasesmith --help

Quick start

cd your-repo
releasesmith generate --no-llm     # writes CHANGELOG.md, fully offline
releasesmith preview --no-llm      # terminal preview, writes nothing
releasesmith stats                 # category chart, scopes, authors

CLI examples

releasesmith generate --since v1.2.0                    # range-limited
releasesmith generate --format html --output site.html  # self-contained page
releasesmith generate --format json                     # machine-readable
releasesmith generate --lang zh-TW                      # 繁體中文標題
releasesmith generate --provider openai                 # + LLM classification
releasesmith generate --provider ollama --model ollama/llama3
releasesmith generate --polish                          # LLM wording polish
releasesmith generate --paths src tests                 # path-filtered
releasesmith generate --include-merge-commits           # keep merges
releasesmith generate --dry-run                         # never writes files
releasesmith diff v1.0.0 v1.1.0                         # entry-level diff
releasesmith tweet --since v1.4.0                       # X/Twitter draft
releasesmith init                                       # guided config setup
releasesmith serve --host 127.0.0.1 --port 8000         # local web UI

Configuration

Copy .releasesmith.toml.example to your repo root as .releasesmith.toml:

[releasesmith]
llm_provider = "openai"        # openai | anthropic | ollama | "" (offline)
model = "gpt-4o-mini"
language = "en"                # en | zh-TW
format = "markdown"
output_file = "CHANGELOG.md"

[releasesmith.github]
repo = "owner/repo"            # enables commit/PR/issue links

[releasesmith.prompts]
classify_system = ""           # optional prompt overrides (merged per-key)
summarize_system = ""

Precedence: CLI flags > RELEASESMITH_* env vars > .releasesmith.toml > packaged defaults. Full field reference: docs/configuration.md.

GitHub Actions integration

name: Changelog check
on: [pull_request]
permissions:
  contents: read
jobs:
  changelog:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0          # full history for accurate ranges
      - uses: astral-sh/setup-uv@v5
        with:
          python-version: "3.12"
      - run: uv tool install releasesmith
      - run: releasesmith generate --no-llm --dry-run

This repository's own CI runs lint + format + mypy strict + tests with an 80% coverage gate on Python 3.11/3.12 (Linux + Windows); the release workflow builds and validates distributions on v* tags with PyPI trusted publishing scaffolding.

HTML output

--format html emits one self-contained file: system font stack, inline CSS, responsive layout, automatic dark mode via prefers-color-scheme, colour-coded category badges, a version timeline, clickable short hashes when [releasesmith.github] repo is set — all content escaped, no JavaScript and no external resources required.

Local Web UI

releasesmith serve                # http://127.0.0.1:8000

Server-rendered form: enter any local repository path, pick since/until, format and language, then preview or download the generated document. The web UI binds loopback only by default and shares the CLI's validation and pipeline code.

Privacy & security note

Commit text is transmitted to a third party only when you enable an LLM provider (via config or flags, without --no-llm). For sensitive repositories prefer --no-llm or self-hosted Ollama, and review history for embedded secrets first. API keys are read exclusively from environment variables and never written to config files, logs or reports.

Development

git clone https://github.com/JToSound/releasesmith && cd releasesmith
uv sync --all-groups
uv run pre-commit install 2>/dev/null || true   # optional
uv run ruff check .                             # lint
uv run ruff format .                            # format
uv run mypy src                                 # strict types
uv run pytest --cov=releasesmith                # tests + coverage gate ≥80%

Architecture: src/releasesmith/core (models, git parser, classifiers, generator, summarizer) → src/releasesmith/renderers (markdown/json/html/ twitter via packaged Jinja2 templates) → src/releasesmith/cli.py + src/releasesmith/web.py (thin interfaces). Providers live in src/releasesmith/providers; prompt templates in src/releasesmith/templates/prompts.

Contributing

Issues and pull requests are welcome. For non-trivial changes please open an issue first; include tests for behavioural changes (pytest) and make sure the quality gates above pass locally.

License

MIT — © JToSound and contributors.