Commit History to Structured Changelog Prompt Template

Engineering leads and release managers need changelogs that categorize every commit by impact: breaking changes, features, fixes, and maintenance. Manual curation is slow and error-prone. This prompt converts a raw git log into a structured changelog with linked issues, contributor attribution, and category assignments. Use it when you have commit history from a version control system and need a draft changelog that a human can review and publish.

The prompt expects a formatted git log as input—typically generated with a command like git log v1.0.0..v1.1.0 --pretty=format:'%h %s (%an) [%ai]' --no-merges. It works best with commit messages that follow a conventional format (e.g., feat:, fix:, BREAKING CHANGE:), but the prompt includes instructions to infer categories from unstructured messages when conventions are absent. The output schema includes fields for category, summary, commit hash, author, date, linked issues, and a migration note flag for breaking changes.

Do not use this prompt for real-time incident communication, legal compliance filings, or security vulnerability disclosures where exact wording is regulated. For security patches, use the Security Patch Release Note Prompt Template instead. For breaking changes that require detailed migration guides, pair this prompt with the Breaking Change Detection and Migration Guidance Prompt Template. Always run the Changelog Entry Validation and QA Prompt Template against the output before publication.

This prompt template transforms a raw git log into a structured changelog suitable for release notes. It instructs the model to categorize each commit as a Breaking Change, Feature, Fix, or Maintenance item, link to referenced issues, and credit contributors. Use this as the foundation for your changelog automation pipeline, adapting the placeholders to match your repository's conventions and output format requirements.

codeCopy
You are a technical release manager converting raw git commit history into a structured changelog.

## INPUT
Commit history (one commit per line, oldest first):

[COMMIT_HISTORY]

codeCopy

## OUTPUT SCHEMA
Return a JSON object with the following structure:
{
  "release_version": "[RELEASE_VERSION]",
  "release_date": "[RELEASE_DATE]",
  "categories": {
    "breaking_changes": [
      {
        "description": "Human-readable summary of the breaking change",
        "commit": "[commit_hash]",
        "issue_refs": ["#123", "#456"],
        "contributors": ["[author_name]"],
        "migration_notes": "What consumers must do to adapt, if known"
      }
    ],
    "features": [
      {
        "description": "Human-readable summary of the new feature",
        "commit": "[commit_hash]",
        "issue_refs": ["#789"],
        "contributors": ["[author_name]"]
      }
    ],
    "fixes": [
      {
        "description": "Human-readable summary of the bug fix",
        "commit": "[commit_hash]",
        "issue_refs": ["#101"],
        "contributors": ["[author_name]"]
      }
    ],
    "maintenance": [
      {
        "description": "Human-readable summary of refactoring, dependency bumps, or CI changes",
        "commit": "[commit_hash]",
        "issue_refs": [],
        "contributors": ["[author_name]"]
      }
    ]
  },
  "contributor_summary": {
    "[author_name]": {
      "commit_count": 5,
      "categories_contributed_to": ["features", "fixes"]
    }
  },
  "statistics": {
    "total_commits": 42,
    "breaking_changes_count": 1,
    "features_count": 5,
    "fixes_count": 12,
    "maintenance_count": 24
  }
}

## CONSTRAINTS
- Categorize each commit into exactly one category: breaking_changes, features, fixes, or maintenance.
- A breaking change is any commit that removes, renames, or alters existing behavior in a way that requires consumer code changes. Look for keywords like "BREAKING", "remove", "deprecate", "rename", or conventional commit "!" suffix.
- Extract issue references from commit messages using patterns like "#123", "fixes #456", or "closes #789".
- Extract contributor names from the commit author field.
- If a commit message is vague (e.g., "fix stuff"), infer the best category from the diff context if available, or default to "maintenance" and note the ambiguity.
- Do not invent changes not present in the commit history.
- If [RELEASE_VERSION] is empty, omit the "release_version" field.
- If [RELEASE_DATE] is empty, omit the "release_date" field.

## EXAMPLES
Input commit: "a1b2c3d feat: add user export endpoint (#42) (Jane Smith)"
Output entry: { "description": "Add user export endpoint", "commit": "a1b2c3d", "issue_refs": ["#42"], "contributors": ["Jane Smith"] } -> category: features

Input commit: "e5f6g7h fix: resolve timeout on large datasets (#88) (John Doe)"
Output entry: { "description": "Resolve timeout on large datasets", "commit": "e5f6g7h", "issue_refs": ["#88"], "contributors": ["John Doe"] } -> category: fixes

Input commit: "i9j0k1l chore: bump lodash to 4.17.21 (Alice Wong)"
Output entry: { "description": "Bump lodash to 4.17.21", "commit": "i9j0k1l", "issue_refs": [], "contributors": ["Alice Wong"] } -> category: maintenance

Before wiring this into production, replace [COMMIT_HISTORY] with your actual git log output (formatted as one commit per line with hash, message, and author). Replace [RELEASE_VERSION] and [RELEASE_DATE] with your release metadata, or remove those fields from the schema if you inject them downstream. Test the prompt against a known release with a manually verified changelog to calibrate category accuracy before automating. For high-stakes releases, always route the output through human review and cross-reference against your issue tracker to catch misclassified or missing entries.

This prompt is designed to run as a step in an automated release pipeline, not as a one-off manual copy-paste. The typical integration point is after a release branch is cut or a tag is pushed, where git log output from the relevant commit range is piped into the prompt. The harness should supply the raw commit history as [COMMIT_HISTORY], a target version string as [VERSION], and a repository identifier as [REPO_NAME]. The prompt expects the commit history to include full commit messages, not just subjects, so the harness must use git log --format=fuller or an equivalent command that captures the body and author fields. If your commit convention uses conventional commits, include that convention in [COMMIT_CONVENTION] to improve categorization accuracy.

Validation and retry logic is critical because changelogs ship to users. After the model returns the structured changelog, the harness must validate the output against the expected JSON schema: confirm that every entry has a non-empty category, description, and commit reference, and that categories are limited to the allowed set (breaking, feature, fix, maintenance, dependency). If validation fails, retry once with the validation errors appended to the prompt as [PREVIOUS_ERRORS]. If the retry also fails, flag the run for human review and do not auto-publish. For contributor attribution, cross-reference extracted author emails against a team roster or .mailmap file to deduplicate identities before the entry is finalized.

Model choice and tool use should favor models with strong structured output support. Use a model that supports JSON mode or function calling with a strict schema, and set response_format to json_schema where available. If your pipeline already uses a GitHub or GitLab API, add a post-processing step that enriches each changelog entry with issue titles and PR descriptions fetched via the API, rather than asking the model to hallucinate them. For high-volume repositories with hundreds of commits per release, split the commit history into batches of 50–100 commits, run the prompt per batch, and merge the results with a deduplication pass. Log every run's input commit range, output, validation result, and reviewer decision for auditability.

Human review gates should be mandatory for any entry categorized as breaking and for any release where the model's confidence score (if you request one in [OUTPUT_SCHEMA]) falls below a threshold. Integrate the review step into your existing PR or release approval workflow: post the generated changelog as a draft in a release issue or PR description, and require an engineering lead or technical writer to approve before the changelog is published to your docs site or GitHub Releases. Avoid the temptation to fully automate changelog publication without review—mischaracterized breaking changes erode developer trust faster than a delayed release note.