shipnote 0.1.0__tar.gz

shipnote-0.1.0/.gitignore

@@ -0,0 +1,22 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.env
+
+# Tooling
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# OS
+.DS_Store
+Thumbs.db
+desktop.ini

shipnote-0.1.0/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## v0.1.0
+
+### Features
+- group commits into Features, Bug Fixes, Performance, Breaking Changes and more
+- understand Conventional Commits, including scopes and breaking-change markers
+- turn commit hashes and `(#123)` PR references into links with `--repo`
+- read an explicit range with `--from` / `--to`, defaulting to the latest tag
+- write notes to a file with `--output`
+
+Initial release.

shipnote-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Seven Of Nine
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

shipnote-0.1.0/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: shipnote
+Version: 0.1.0
+Summary: Generate clean, grouped release notes from your git history. Zero dependencies.
+Project-URL: Homepage, https://github.com/Sev7nOfNine/shipnote
+Project-URL: Repository, https://github.com/Sev7nOfNine/shipnote
+Project-URL: Issues, https://github.com/Sev7nOfNine/shipnote/issues
+Author: Seven Of Nine
+License: MIT
+License-File: LICENSE
+Keywords: automation,changelog,cli,conventional-commits,git,maintainer,release,release-notes
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Version Control :: Git
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == 'test'
+Description-Content-Type: text/markdown
+
+# shipnote
+
+**Generate clean, grouped release notes straight from your git history — with zero dependencies.**
+
+`shipnote` reads the commits between two refs, understands
+[Conventional Commits](https://www.conventionalcommits.org/), and renders tidy
+markdown release notes grouped by Features, Bug Fixes, Performance, Breaking
+Changes, and more. No config file, no extra packages, no network calls.
+
+It is built for the boring-but-constant chore every maintainer knows: writing
+the changelog at release time.
+
+## Why
+
+Most changelog tools pull in a tree of dependencies, want a config file, or lock
+you into one commit convention. `shipnote` is a single small package that uses
+nothing but the Python standard library and the `git` you already have. Drop it
+into any project or CI job and get readable notes in one command.
+
+## Install
+
+```bash
+pip install shipnote
+# or, for an isolated CLI:
+pipx install shipnote
+```
+
+Requires Python 3.8+ and `git` on your PATH.
+
+## Usage
+
+From inside a git repository:
+
+```bash
+# Notes from the latest tag up to HEAD
+shipnote
+
+# A titled section for a specific version, with commit/PR links
+shipnote --title v1.2.0 --repo me/myproject
+
+# An explicit range, written to a file
+shipnote --from v1.1.0 --to v1.2.0 --output RELEASE_NOTES.md
+```
+
+If the repo has no tags yet, `shipnote` walks the whole history.
+
+### Options
+
+| Flag | Description |
+| --- | --- |
+| `--from REF` | Start ref, exclusive. Defaults to the latest tag. |
+| `--to REF` | End ref, inclusive. Defaults to `HEAD`. |
+| `-t`, `--title TEXT` | Heading for the notes, e.g. the version. |
+| `--repo OWNER/NAME` | Turn commit hashes and `(#123)` PR refs into links. |
+| `--base-url URL` | Base URL for links (default `https://github.com`). |
+| `-o`, `--output FILE` | Write to a file instead of stdout. |
+| `-C DIR` | Run as if started in `DIR`. |
+
+## Example output
+
+```markdown
+## v1.2.0
+
+### Breaking Changes
+- drop Python 3.7 support (`a1b2c3d`)
+
+### Features
+- **api:** add streaming endpoint ([#42](https://github.com/me/proj/pull/42), [`9f8e7d6`](https://github.com/me/proj/commit/9f8e7d6))
+
+### Bug Fixes
+- handle an empty commit range gracefully (`c4d5e6f`)
+```
+
+## In CI
+
+Use it in a release workflow to draft notes from the just-tagged range:
+
+```yaml
+- name: Draft release notes
+  run: |
+    pip install shipnote
+    shipnote --title "${GITHUB_REF_NAME}" --repo "${GITHUB_REPOSITORY}" -o notes.md
+```
+
+## How it groups commits
+
+Conventional types map to sections: `feat` → Features, `fix` → Bug Fixes,
+`perf` → Performance, `docs` → Documentation, `refactor` → Refactoring,
+`test` → Tests, `build` → Build System, `ci` → CI, `style` → Styles,
+`chore` → Chores, `revert` → Reverts. Anything that does not match falls under
+**Other**, so no commit is ever silently dropped. Commits marked breaking (a `!`
+after the type, or a `BREAKING CHANGE` footer) are surfaced under **Breaking
+Changes**.
+
+## Development
+
+```bash
+pip install -e .
+python -m pytest
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

shipnote-0.1.0/README.md

@@ -0,0 +1,104 @@
+# shipnote
+
+**Generate clean, grouped release notes straight from your git history — with zero dependencies.**
+
+`shipnote` reads the commits between two refs, understands
+[Conventional Commits](https://www.conventionalcommits.org/), and renders tidy
+markdown release notes grouped by Features, Bug Fixes, Performance, Breaking
+Changes, and more. No config file, no extra packages, no network calls.
+
+It is built for the boring-but-constant chore every maintainer knows: writing
+the changelog at release time.
+
+## Why
+
+Most changelog tools pull in a tree of dependencies, want a config file, or lock
+you into one commit convention. `shipnote` is a single small package that uses
+nothing but the Python standard library and the `git` you already have. Drop it
+into any project or CI job and get readable notes in one command.
+
+## Install
+
+```bash
+pip install shipnote
+# or, for an isolated CLI:
+pipx install shipnote
+```
+
+Requires Python 3.8+ and `git` on your PATH.
+
+## Usage
+
+From inside a git repository:
+
+```bash
+# Notes from the latest tag up to HEAD
+shipnote
+
+# A titled section for a specific version, with commit/PR links
+shipnote --title v1.2.0 --repo me/myproject
+
+# An explicit range, written to a file
+shipnote --from v1.1.0 --to v1.2.0 --output RELEASE_NOTES.md
+```
+
+If the repo has no tags yet, `shipnote` walks the whole history.
+
+### Options
+
+| Flag | Description |
+| --- | --- |
+| `--from REF` | Start ref, exclusive. Defaults to the latest tag. |
+| `--to REF` | End ref, inclusive. Defaults to `HEAD`. |
+| `-t`, `--title TEXT` | Heading for the notes, e.g. the version. |
+| `--repo OWNER/NAME` | Turn commit hashes and `(#123)` PR refs into links. |
+| `--base-url URL` | Base URL for links (default `https://github.com`). |
+| `-o`, `--output FILE` | Write to a file instead of stdout. |
+| `-C DIR` | Run as if started in `DIR`. |
+
+## Example output
+
+```markdown
+## v1.2.0
+
+### Breaking Changes
+- drop Python 3.7 support (`a1b2c3d`)
+
+### Features
+- **api:** add streaming endpoint ([#42](https://github.com/me/proj/pull/42), [`9f8e7d6`](https://github.com/me/proj/commit/9f8e7d6))
+
+### Bug Fixes
+- handle an empty commit range gracefully (`c4d5e6f`)
+```
+
+## In CI
+
+Use it in a release workflow to draft notes from the just-tagged range:
+
+```yaml
+- name: Draft release notes
+  run: |
+    pip install shipnote
+    shipnote --title "${GITHUB_REF_NAME}" --repo "${GITHUB_REPOSITORY}" -o notes.md
+```
+
+## How it groups commits
+
+Conventional types map to sections: `feat` → Features, `fix` → Bug Fixes,
+`perf` → Performance, `docs` → Documentation, `refactor` → Refactoring,
+`test` → Tests, `build` → Build System, `ci` → CI, `style` → Styles,
+`chore` → Chores, `revert` → Reverts. Anything that does not match falls under
+**Other**, so no commit is ever silently dropped. Commits marked breaking (a `!`
+after the type, or a `BREAKING CHANGE` footer) are surfaced under **Breaking
+Changes**.
+
+## Development
+
+```bash
+pip install -e .
+python -m pytest
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

shipnote-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "shipnote"
+version = "0.1.0"
+description = "Generate clean, grouped release notes from your git history. Zero dependencies."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "Seven Of Nine" }]
+keywords = [
+    "changelog",
+    "release-notes",
+    "git",
+    "conventional-commits",
+    "release",
+    "maintainer",
+    "cli",
+    "automation",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Software Development :: Version Control :: Git",
+    "Topic :: Utilities",
+]
+
+[project.urls]
+Homepage = "https://github.com/Sev7nOfNine/shipnote"
+Repository = "https://github.com/Sev7nOfNine/shipnote"
+Issues = "https://github.com/Sev7nOfNine/shipnote/issues"
+
+[project.optional-dependencies]
+test = ["pytest>=7"]
+
+[project.scripts]
+shipnote = "shipnote.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/shipnote"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/shipnote", "README.md", "LICENSE", "CHANGELOG.md", "tests"]

shipnote-0.1.0/src/shipnote/__init__.py

@@ -0,0 +1,5 @@
+"""shipnote — generate clean, grouped release notes from your git history."""
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

shipnote-0.1.0/src/shipnote/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

shipnote-0.1.0/src/shipnote/cli.py

@@ -0,0 +1,96 @@
+"""Command-line interface for shipnote."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import List, Optional
+
+from . import __version__
+from .core import GitError, get_commits, render_markdown, resolve_range
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="shipnote",
+        description="Generate clean, grouped release notes from your git history.",
+    )
+    parser.add_argument(
+        "--from",
+        dest="frm",
+        metavar="REF",
+        help="start ref (exclusive). Defaults to the latest tag, or the whole "
+        "history if there are no tags.",
+    )
+    parser.add_argument(
+        "--to",
+        dest="to",
+        metavar="REF",
+        default="HEAD",
+        help="end ref (inclusive). Defaults to HEAD.",
+    )
+    parser.add_argument(
+        "-t",
+        "--title",
+        metavar="TEXT",
+        help="heading for the notes, e.g. the version being released (v1.2.0).",
+    )
+    parser.add_argument(
+        "--repo",
+        metavar="OWNER/NAME",
+        help="GitHub repo slug used to turn commits and PRs into links.",
+    )
+    parser.add_argument(
+        "--base-url",
+        metavar="URL",
+        default="https://github.com",
+        help="base URL for links (default: https://github.com).",
+    )
+    parser.add_argument(
+        "-o",
+        "--output",
+        metavar="FILE",
+        help="write the notes to FILE instead of stdout.",
+    )
+    parser.add_argument(
+        "-C",
+        dest="cwd",
+        metavar="DIR",
+        help="run as if shipnote were started in DIR.",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version="%(prog)s {0}".format(__version__),
+    )
+    return parser
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    try:
+        rev_range = resolve_range(args.frm, args.to, cwd=args.cwd)
+        commits = get_commits(rev_range, cwd=args.cwd)
+    except GitError as exc:
+        parser.exit(2, "shipnote: {0}\n".format(exc))
+
+    notes = render_markdown(
+        commits,
+        title=args.title,
+        repo=args.repo,
+        base_url=args.base_url,
+    )
+
+    if args.output:
+        with open(args.output, "w", encoding="utf-8") as handle:
+            handle.write(notes)
+    else:
+        sys.stdout.write(notes)
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

shipnote-0.1.0/src/shipnote/core.py

@@ -0,0 +1,256 @@
+"""Core logic for shipnote: parse git commits and render release notes.
+
+The functions here are deliberately split into two layers:
+
+* Pure functions (``parse_commit``, ``categorize``, ``render_markdown``) that
+  operate on plain data and are trivially unit-testable without a git repo.
+* Thin git wrappers (``run_git``, ``latest_tag``, ``get_commits``,
+  ``resolve_range``) that shell out to ``git``.
+"""
+
+from __future__ import annotations
+
+import re
+import subprocess
+from dataclasses import dataclass
+from typing import Dict, List, Optional, Sequence
+
+# A conventional-commit subject, e.g. "feat(api)!: add streaming endpoint".
+_CONVENTIONAL_RE = re.compile(
+    r"^(?P<type>[a-z]+)"
+    r"(?:\((?P<scope>[^)]+)\))?"
+    r"(?P<breaking>!)?"
+    r":\s*(?P<subject>.+)$",
+    re.IGNORECASE,
+)
+
+# A trailing PR reference GitHub appends on squash-merge, e.g. "(#42)".
+_PR_RE = re.compile(r"\(#(\d+)\)\s*$")
+
+# Map a conventional type to a human section title.
+TYPE_SECTIONS: Dict[str, str] = {
+    "feat": "Features",
+    "fix": "Bug Fixes",
+    "perf": "Performance",
+    "refactor": "Refactoring",
+    "docs": "Documentation",
+    "test": "Tests",
+    "build": "Build System",
+    "ci": "CI",
+    "style": "Styles",
+    "chore": "Chores",
+    "revert": "Reverts",
+}
+
+# The order sections appear in the rendered notes.
+SECTION_ORDER: List[str] = [
+    "Breaking Changes",
+    "Features",
+    "Bug Fixes",
+    "Performance",
+    "Refactoring",
+    "Documentation",
+    "Tests",
+    "Build System",
+    "CI",
+    "Styles",
+    "Chores",
+    "Reverts",
+    "Other",
+]
+
+
+class GitError(RuntimeError):
+    """Raised when an underlying git command fails."""
+
+
+@dataclass
+class Commit:
+    """A single parsed commit."""
+
+    sha: str
+    subject: str
+    body: str = ""
+    type: Optional[str] = None
+    scope: Optional[str] = None
+    breaking: bool = False
+    pr: Optional[int] = None
+
+    @property
+    def short_sha(self) -> str:
+        return self.sha[:7]
+
+
+def parse_commit(sha: str, subject: str, body: str = "") -> Commit:
+    """Parse a raw commit into a :class:`Commit`, recognising conventional commits."""
+    subject = subject.strip()
+    body = body.strip()
+
+    pr: Optional[int] = None
+    pr_match = _PR_RE.search(subject)
+    if pr_match:
+        pr = int(pr_match.group(1))
+        # Drop the trailing "(#42)" so it is not repeated next to the link.
+        subject = _PR_RE.sub("", subject).strip()
+
+    breaking = "BREAKING CHANGE" in body or "BREAKING-CHANGE" in body
+
+    match = _CONVENTIONAL_RE.match(subject)
+    if not match:
+        return Commit(sha=sha, subject=subject, body=body, breaking=breaking, pr=pr)
+
+    ctype = match.group("type").lower()
+    if match.group("breaking"):
+        breaking = True
+
+    return Commit(
+        sha=sha,
+        subject=match.group("subject").strip(),
+        body=body,
+        type=ctype,
+        scope=match.group("scope"),
+        breaking=breaking,
+        pr=pr,
+    )
+
+
+def categorize(commits: Sequence[Commit]) -> "Dict[str, List[Commit]]":
+    """Group commits into ordered sections.
+
+    Breaking changes are surfaced in their own section and are not duplicated
+    under their conventional type.
+    """
+    sections: Dict[str, List[Commit]] = {name: [] for name in SECTION_ORDER}
+    for commit in commits:
+        if commit.breaking:
+            sections["Breaking Changes"].append(commit)
+            continue
+        section = TYPE_SECTIONS.get(commit.type or "", "Other")
+        sections[section].append(commit)
+    return {name: items for name, items in sections.items() if items}
+
+
+def _render_commit(commit: Commit, repo: Optional[str], base_url: str) -> str:
+    bullet = commit.subject
+    if commit.scope:
+        bullet = "**{0}:** {1}".format(commit.scope, bullet)
+
+    refs: List[str] = []
+    if commit.pr is not None:
+        if repo:
+            refs.append("[#{0}]({1}/{2}/pull/{0})".format(commit.pr, base_url, repo))
+        else:
+            refs.append("#{0}".format(commit.pr))
+    if repo:
+        refs.append(
+            "[`{0}`]({1}/{2}/commit/{3})".format(
+                commit.short_sha, base_url, repo, commit.sha
+            )
+        )
+    else:
+        refs.append("`{0}`".format(commit.short_sha))
+
+    return "- {0} ({1})".format(bullet, ", ".join(refs))
+
+
+def render_markdown(
+    commits: Sequence[Commit],
+    title: Optional[str] = None,
+    repo: Optional[str] = None,
+    base_url: str = "https://github.com",
+) -> str:
+    """Render grouped commits to a markdown release-notes string."""
+    base_url = base_url.rstrip("/")
+    lines: List[str] = []
+    if title:
+        lines.append("## {0}".format(title))
+        lines.append("")
+
+    sections = categorize(commits)
+    if not sections:
+        lines.append("_No notable changes._")
+        return "\n".join(lines).rstrip() + "\n"
+
+    for name in SECTION_ORDER:
+        items = sections.get(name)
+        if not items:
+            continue
+        lines.append("### {0}".format(name))
+        for commit in items:
+            lines.append(_render_commit(commit, repo, base_url))
+        lines.append("")
+
+    return "\n".join(lines).rstrip() + "\n"
+
+
+# --- git wrappers -------------------------------------------------------------
+
+# Field/record separators unlikely to appear in commit text.
+_FIELD_SEP = "\x1f"
+_RECORD_SEP = "\x1e"
+
+
+def run_git(args: Sequence[str], cwd: Optional[str] = None) -> str:
+    """Run a git command and return stdout, raising :class:`GitError` on failure."""
+    try:
+        result = subprocess.run(
+            ["git", *args],
+            cwd=cwd,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+        )
+    except FileNotFoundError as exc:  # git not installed
+        raise GitError("git executable not found on PATH") from exc
+
+    if result.returncode != 0:
+        raise GitError(result.stderr.strip() or "git {0} failed".format(" ".join(args)))
+    return result.stdout
+
+
+def latest_tag(cwd: Optional[str] = None) -> Optional[str]:
+    """Return the most recent tag reachable from HEAD, or ``None`` if there is none."""
+    try:
+        out = run_git(["describe", "--tags", "--abbrev=0"], cwd=cwd)
+    except GitError:
+        return None
+    tag = out.strip()
+    return tag or None
+
+
+def resolve_range(
+    frm: Optional[str], to: str, cwd: Optional[str] = None
+) -> str:
+    """Build the git revision range to read commits from.
+
+    With no explicit ``frm``, fall back to the latest tag, then to the full
+    history if the repo has no tags yet.
+    """
+    if frm:
+        return "{0}..{1}".format(frm, to)
+    tag = latest_tag(cwd=cwd)
+    if tag:
+        return "{0}..{1}".format(tag, to)
+    return to
+
+
+def get_commits(rev_range: str, cwd: Optional[str] = None) -> List[Commit]:
+    """Read and parse commits in ``rev_range`` (newest first), skipping merges."""
+    fmt = _FIELD_SEP.join(["%H", "%s", "%b"]) + _RECORD_SEP
+    out = run_git(
+        ["log", "--no-merges", "--format={0}".format(fmt), rev_range],
+        cwd=cwd,
+    )
+    commits: List[Commit] = []
+    for record in out.split(_RECORD_SEP):
+        record = record.strip("\n")
+        if not record:
+            continue
+        parts = record.split(_FIELD_SEP)
+        sha = parts[0] if len(parts) > 0 else ""
+        subject = parts[1] if len(parts) > 1 else ""
+        body = parts[2] if len(parts) > 2 else ""
+        if not sha:
+            continue
+        commits.append(parse_commit(sha, subject, body))
+    return commits

shipnote-0.1.0/tests/test_core.py

@@ -0,0 +1,93 @@
+"""Unit tests for shipnote's pure logic (no git repo required)."""
+
+from shipnote.core import (
+    Commit,
+    categorize,
+    parse_commit,
+    render_markdown,
+)
+
+
+def test_parse_plain_commit():
+    commit = parse_commit("a" * 40, "just a plain message")
+    assert commit.type is None
+    assert commit.subject == "just a plain message"
+    assert commit.breaking is False
+    assert commit.short_sha == "aaaaaaa"
+
+
+def test_parse_conventional_with_scope():
+    commit = parse_commit("b" * 40, "feat(api): add streaming endpoint")
+    assert commit.type == "feat"
+    assert commit.scope == "api"
+    assert commit.subject == "add streaming endpoint"
+    assert commit.breaking is False
+
+
+def test_parse_breaking_bang():
+    commit = parse_commit("c" * 40, "feat!: drop python 3.7")
+    assert commit.type == "feat"
+    assert commit.breaking is True
+
+
+def test_parse_breaking_footer():
+    commit = parse_commit(
+        "d" * 40,
+        "refactor: rework config",
+        body="BREAKING CHANGE: config file moved",
+    )
+    assert commit.breaking is True
+
+
+def test_parse_pr_reference():
+    commit = parse_commit("e" * 40, "fix: handle empty range (#42)")
+    assert commit.pr == 42
+    assert commit.subject == "handle empty range"
+
+
+def test_categorize_groups_and_drops_empty():
+    commits = [
+        parse_commit("1" * 40, "feat: a"),
+        parse_commit("2" * 40, "fix: b"),
+        parse_commit("3" * 40, "chore: c"),
+    ]
+    grouped = categorize(commits)
+    assert set(grouped) == {"Features", "Bug Fixes", "Chores"}
+
+
+def test_categorize_breaking_not_duplicated():
+    commits = [parse_commit("4" * 40, "feat!: big change")]
+    grouped = categorize(commits)
+    assert "Breaking Changes" in grouped
+    assert "Features" not in grouped
+
+
+def test_render_unknown_type_goes_to_other():
+    commits = [Commit(sha="f" * 40, subject="something", type="wip")]
+    out = render_markdown(commits)
+    assert "### Other" in out
+    assert "- something (`fffffff`)" in out
+
+
+def test_render_with_repo_links():
+    commits = [parse_commit("a1b2c3d4e5" + "0" * 30, "fix: thing (#7)")]
+    out = render_markdown(commits, title="v1.0.0", repo="me/proj")
+    assert out.startswith("## v1.0.0")
+    assert "[#7](https://github.com/me/proj/pull/7)" in out
+    assert "https://github.com/me/proj/commit/" in out
+
+
+def test_render_empty():
+    out = render_markdown([])
+    assert "No notable changes" in out
+
+
+def test_render_section_order():
+    commits = [
+        parse_commit("1" * 40, "docs: d"),
+        parse_commit("2" * 40, "feat: f"),
+        parse_commit("3" * 40, "fix: x"),
+    ]
+    out = render_markdown(commits)
+    assert out.index("### Features") < out.index("### Bug Fixes")
+    assert out.index("### Bug Fixes") < out.index("### Documentation")