Git Changelog 自動化：從 Commit、PR 到 Release Notes

git log --oneline v1.7.0..HEAD

9a3c121 fix lint
4be02d8 merge main
08ec733 wip
7d9fe11 refactor helper
15cf820 add csv export (#184)

previous_ref..current_ref

git rev-parse --verify "v1.7.0^{commit}"
git rev-parse --verify "v1.8.0^{commit}"

git log \
  --first-parent \
  --format='%H%x09%h%x09%aI%x09%s' \
  v1.7.0..v1.8.0

mkdir -p build/release
git log \
  --first-parent \
  --format='%H%x09%h%x09%aI%x09%s' \
  "$PREVIOUS_REF..$CURRENT_REF" \
  > build/release/commits.tsv

feat(export): add CSV streaming mode
fix(auth): refresh expired session
docs: explain proxy settings
chore(deps): bump httpx
feat(api)!: remove legacy endpoint

from __future__ import annotations
import argparse
import re
from dataclasses import dataclass
from pathlib import Path
PATTERN = re.compile(
    r"^(?P<kind>[a-z]+)(?:\((?P<scope>[^)]+)\))?"
    r"(?P<breaking>!)?:\s+(?P<summary>.+)$"
)
CATEGORIES = {
    "feat": "Added",
    "fix": "Fixed",
    "perf": "Performance",
    "refactor": "Changed",
    "docs": "Documentation",
}
@dataclass(frozen=True)
class Change:
    full_hash: str
    short_hash: str
    category: str
    summary: str
    breaking: bool
def parse(line: str) -> Change | None:
    parts = line.rstrip("\n").split("\t", maxsplit=3)
    if len(parts) != 4:
        raise ValueError(f"invalid TSV row: {line!r}")
    full_hash, short_hash, _date, subject = parts
    match = PATTERN.match(subject)
    if match is None or match["kind"] not in CATEGORIES:
        return None
    summary = match["summary"].strip()
    if match["scope"]:
        summary = f"**{match['scope']}:** {summary}"
    return Change(
        full_hash, short_hash, CATEGORIES[match["kind"]],
        summary, bool(match["breaking"])
    )
def render(changes: list[Change], repo_url: str) -> str:
    lines = ["# Release notes", ""]
    groups = ["Breaking changes", *CATEGORIES.values()]
    for group in groups:
        selected = [
            item for item in changes
            if (group == "Breaking changes" and item.breaking)
            or (group == item.category and not item.breaking)
        ]
        if not selected:
            continue
        lines.extend([f"## {group}", ""])
        for item in selected:
            url = f"{repo_url}/commit/{item.full_hash}"
            lines.append(f"- {item.summary} ([`{item.short_hash}`]({url}))")
        lines.append("")
    return "\n".join(lines).rstrip() + "\n"
def main() -> None:
    parser = argparse.ArgumentParser()
    parser.add_argument("input", type=Path)
    parser.add_argument("output", type=Path)
    parser.add_argument("--repo-url", required=True)
    args = parser.parse_args()
    changes = [
        change for line in args.input.read_text().splitlines(True)
        if (change := parse(line)) is not None
    ]
    if not changes:
        raise SystemExit("no public changes found")
    args.output.parent.mkdir(parents=True, exist_ok=True)
    args.output.write_text(render(changes, args.repo_url.rstrip("/")))
if __name__ == "__main__":
    main()

python scripts/build_changelog.py \
  build/release/commits.tsv \
  build/release/RELEASE_NOTES.md \
  --repo-url https://github.com/acme/widget

git log \
  --first-parent \
  --format='%s' \
  "$PREVIOUS_REF..$CURRENT_REF" \
  | grep -Ev '^(feat|fix|perf|refactor|docs|chore|ci|test)(\([^)]+\))?!?: '

changelog:
  exclude:
    labels:
      - skip-changelog
  categories:
    - title: "Breaking changes"
      labels: ["type: breaking"]
    - title: "New features"
      labels: ["type: feature"]
    - title: "Bug fixes"
      labels: ["type: bug"]
    - title: "Maintenance"
      labels: ["dependencies", "documentation"]
    - title: "Other changes"
      labels: ["*"]

gh api \
  --method POST \
  repos/{owner}/{repo}/releases/generate-notes \
  -f tag_name="$CURRENT_REF" \
  -f previous_tag_name="$PREVIOUS_REF" \
  -f target_commitish='main' \
  > build/release/generated.json

jq -r '.body' \
  build/release/generated.json \
  > build/release/github-notes.md

-f configuration_file_path='.github/custom_release_config.yml'

name: Preview release notes
on: workflow_dispatch
permissions:
  contents: read
jobs:
  preview:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
        with: { fetch-depth: 0 }
      - run: ./scripts/export_commits.sh "$PREVIOUS_REF" "$CURRENT_REF"
      - run: python scripts/build_changelog.py build/release/commits.tsv build/release/RELEASE_NOTES.md --repo-url "https://github.com/${GITHUB_REPOSITORY}"
      - uses: actions/upload-artifact@v4
        with: { name: release-notes-preview, path: build/release/ }

test -s build/release/commits.tsv || {
  echo "No commits in requested range" >&2
  exit 1
}

if grep -En 'TODO|TBD|待補|待確認' build/release/RELEASE_NOTES.md; then
  echo "Release notes contain placeholders" >&2
  exit 1
fi

from collections import Counter
from pathlib import Path
import re

text = Path("build/release/RELEASE_NOTES.md").read_text()
items = [line for line in text.splitlines() if line.startswith("- ")]
missing = [line for line in items if "/commit/" not in line]
refs = re.findall(r"/commit/([0-9a-f]{7,40})", text)
duplicates = [ref for ref, count in Counter(refs).items() if count > 1]

if missing or duplicates:
    raise SystemExit({"missing": missing, "duplicates": duplicates})