Skip to content

feat: Phase 7 — PR summaries, release changelogs, and unified orchestrator - #12

Merged
getdownandcode merged 4 commits into
mainfrom
feat
Sep 19, 2026
Merged

feat: Phase 7 — PR summaries, release changelogs, and unified orchestrator#12
getdownandcode merged 4 commits into
mainfrom
feat

Conversation

@getdownandcode

@getdownandcode getdownandcode commented Sep 18, 2026

Copy link
Copy Markdown
Owner

Summary

Phase 7 extends gitmate beyond single-commit generation with two daily-use capabilities:

  1. gitmate pr-summary: Compares the current branch against a base branch (main by default), extracts the 3-dot diff (base...HEAD), applies token budgeting & chunking, and generates a structured GitHub Markdown PR description. Automatically copies the description to the system clipboard (pyperclip) and optionally triggers the GitHub CLI PR creation flow (--create-pr).
  2. gitmate changelog: Walks git commit history between two tags/refs (--from and --to), categorizes commits using conventional-commit rules (Features, Bug Fixes, Performance & Refactoring, Documentation, Maintenance & Tooling, and Other Changes fallback bucket for zero lost commits), synthesizes them with optional file diff notes, and outputs directly to stdout (Unix pipe friendly) or to an output file (-o / --output).
  3. Extracted unified LLM pipeline into gitmate.orchestrator.run_generation_pipeline reused across commit, pr-summary, and changelog.

Changes

  • Core Orchestration:
    • src/gitmate/orchestrator.py: Centralized LLM pipeline handling token budgeting, chunking of omitted diffs, caching, provider calls, cost calculation, and fallback.
    • src/gitmate/prompt.py: Added generic render_prompt and alias for changelog template.
    • src/gitmate/templates/changelog.txt: Versioned prompt template for release changelogs.
    • src/gitmate/fallback.py: Refactored generate_commit_message to delegate to run_generation_pipeline; added generate_fallback_pr_summary and generate_fallback_changelog.
  • PR Summary:
    • src/gitmate/pr_summary.py: Full PR summary generation pipeline, headless-resilient clipboard handling, and optional gh pr create dispatch.
  • Changelog:
    • src/gitmate/changelog.py: CommitLogEntry dataclass, conventional-commit parser, semantic category grouping, stdout/file output handling.
  • CLI:
    • src/gitmate/cli.py: Implemented real pr-summary and changelog commands.
  • Telemetry:
    • Telemetry recording with command="pr_summary"" and command="changelog"" wired into metrics.db.
  • Tests:
    • tests/test_pr_summary.py: Branch comparison, mock provider, clipboard fallback, gh CLI handling, budget cap abort, telemetry recording.
    • tests/test_changelog.py: Conventional commit parsing, grouping, real git tag extraction, file output, telemetry recording.
    • tests/test_cli.py: CLI integration tests for pr-summary and changelog.

Verification

  • uv run pytest: 253 passed in 13s (0 regressions, 22 new tests).
  • uv run ruff check .: 0 errors / clean.
  • uv run ruff format --check .: 35 files clean.
  • uv run mypy src tests: strict mode clean across 32 source files.

@getdownandcode
feat: Phase 7 — PR summaries, release changelogs, and unified orchest…
ed44b47 
…rator
@getdownandcode
fix: address PR #12 review feedback on exit codes, stderr routing, an…
2cda9ef 
…d orchestrator consolidation

- #1 (Blocker): Fail loud with exit code 1 on git errors, budget cap breaches, and gh CLI errors across pr-summary and changelog CLI commands.
- #2: Prevent duplicate printing when no changes/commits exist by early returning None.
- #3: Route diagnostic warnings, budget alerts, and error messages to stderr console (err_console) to keep stdout clean for Unix piping.
- #4: Correctly parse and surface breaking changes (exclamation mark and BREAKING CHANGE: footers) in conventional commits and templates.
- #5: Bump changelog template to version 2, including from_ref..to_ref range and explicit release headers.
- #6: Support --title (-t) flag in pr-summary and propagate gh pr create failures.
- #7: Remove dead head argument from fallback PR summary.
- #8: Consolidate duplicate budget checking, safe telemetry recording, and heuristic token counters into orchestrator.py.
- #9: Enforce strict type hints with CommitLogEntry in fallback.py.
@getdownandcode

getdownandcode commented Sep 19, 2026

Copy link
Copy Markdown
Owner Author

Review Feedback Resolutions & Fixes

Thank you for the rigorous review! All findings from the review have been addressed in commit 2cda9ef. Here is a summary of the fixes:

1. Blocker: Fail loud with Exit Code 1 on Errors (#1)

  • gitmate pr-summary and gitmate changelog now catch GitCommandError, BudgetCapExceededError, and GitHubCliError.
  • Instead of returning exit code 0 or swallowing errors, the CLI prints the error to stderr via err_console and terminates with sys.exit(1), preventing silent failures in CI release scripts (e.g. gitmate changelog ... > CHANGELOG.md).
  • committer.py, pr_summary.py, and changelog.py now uniformly raise BudgetCapExceededError if the monthly budget cap has been reached.

2. Eliminate Duplicate Output on Empty Changes (#2)

  • When no changes are found between branches or refs, CLI functions early-return None after printing the notification, eliminating duplicate prints in the CLI.

3. Clean Unix stdout Piping via stderr Diagnostics (#3)

  • Added dedicated err_console = Console(stderr=True).
  • All user-facing diagnostics, cost alerts, fallback notices, and error messages are routed to err_console.
  • Stdout is reserved strictly for the generated Markdown output, ensuring gitmate changelog --from v1.0 --to v2.0 > CHANGELOG.md produces clean Markdown without terminal warnings or progress text.

4. Breaking Changes Recognition in Conventional Commits (#4)

  • Added is_breaking: bool to CommitLogEntry.
  • parse_commit_message now detects both ! type suffixes (e.g., feat!: drop python 3.10 support) and BREAKING CHANGE: / BREAKING-CHANGE: footers.
  • Breaking changes are highlighted in prompt formatting and prefixed with ⚠ **BREAKING**: in deterministic fallback changelogs.

5. Changelog Template Version Bump (#5)

  • Bumped templates/changelog.txt to version: 2.
  • Updated the prompt template to explicitly reference the $from_ref..$to_ref range and $to_ref in section headings.

6. Support --title in pr-summary and Validate gh Execution (#6)

  • Added --title / -t option to gitmate pr-summary.
  • Verified gh pr create execution: non-zero return codes from subprocess.run now raise GitHubCliError, terminating the command with exit code 1.

7. Ambiguity Resolution on --head (#7)

  • Verified that --head was never exposed as a CLI flag in cli.py (which only accepts an optional [BASE] argument, comparing base...HEAD).
  • The head parameter in generate_fallback_pr_summary was unused dead code; removing it adheres to YAGNI and standard git workflow.

8. Deduplicate Logic into orchestrator.py (#8)

  • Centralized BudgetCapExceededError, check_budget_cap, and safe_record_telemetry in gitmate.orchestrator.
  • Replaced redundant private helpers across committer.py, pr_summary.py, and changelog.py with shared orchestrator functions.
  • Introduced HeuristicTokenCounter in token_budget.py and made it the default counter in run_generation_pipeline when a provider is supplied without an explicit counter.

9. Strict Type Hints (#9)

  • Replaced Any with list[CommitLogEntry] (guarded under TYPE_CHECKING) in src/gitmate/fallback.py.

Verification

  • Test Suite: 264 passed in 12.70s (uv run pytest) — 0 regressions, all error and exit code paths covered.
  • Linter & Formatter: uv run ruff check . and uv run ruff format --check . passed cleanly across all 35 files.
  • Type Checker: uv run mypy src tests passed with 0 issues in strict mode.

@getdownandcode
getdownandcode merged commit 16323ed into main Sep 19, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

See More

Successfully merging this pull request may close these issues.

1 participant

@getdownandcode