Commit Diff to Release Note Prompt Template

This prompt is designed for release managers and developer relations engineers who need to convert raw git diff output into structured, user-facing release notes. The core job-to-be-done is transforming a technical, line-level code change into a clear, categorized summary that communicates value to end-users, highlights bug fixes, and explicitly calls out breaking changes. Use this prompt when you have a concrete diff from a single commit or a small, logically grouped set of commits and you need a first draft of a release note entry that is grounded in the actual code change, not in a PR description or issue tracker summary.

The ideal user is someone who owns the release communication pipeline and is responsible for accuracy. You should not use this prompt for generating an entire version's release notes from hundreds of merged PRs; for that, use the 'Release Note Draft from Merged PRs Prompt Template'. This prompt is also unsuitable for generating changelogs from commit messages alone without the underlying diff, as it relies on code-level evidence to prevent hallucination. The required context includes the raw unified diff, the commit message for added semantic intent, and optionally a [CONSTRAINTS] block specifying the target audience's technical level and any company style guide rules. Without the diff, the model will invent features and fixes that don't exist.

Before integrating this prompt into a CI pipeline, you must implement a validation harness that checks the output against the source diff. A common failure mode is the model generating a 'feature' description for a refactoring change that has no user-facing impact. Your next step should be to pair this prompt with the 'Release Note Hallucination and Factuality Check Prompt' to create an automated accuracy gate. Always require human review for any entry flagged as a breaking change before publishing.

This prompt template is designed to be copied directly into your AI harness. It accepts a raw commit diff and produces a structured release note entry that categorizes changes, highlights breaking changes, and summarizes features and fixes. The square-bracket placeholders—[INPUT_DIFF], [OUTPUT_SCHEMA], [CONSTRAINTS], and [EXAMPLES]—are the only parts you need to replace before use. The template forces the model to ground every claim in the provided diff, reducing hallucination risk.

codeCopy
You are a release note generator. Your task is to analyze the provided commit diff and produce a structured, user-facing release note entry.

## Input
Commit Diff:

[INPUT_DIFF]

codeCopy

## Output Schema
You must output a valid JSON object conforming to this schema:
[OUTPUT_SCHEMA]

## Constraints
- Ground every statement in the provided diff. Do not invent features, fixes, or impacts not present in the diff.
- If a breaking change is detected, set `breaking_change` to `true` and provide a clear migration note in the `breaking_change_description` field.
- Categorize each change as `feature`, `bug_fix`, `deprecation`, `security`, or `other`.
- If the diff contains no user-facing changes, return `{"user_facing": false, "reason": "No user-facing changes detected."}`.
- [CONSTRAINTS]

## Examples
[EXAMPLES]

## Risk Level
[RISK_LEVEL]

To adapt this template, replace [INPUT_DIFF] with the raw diff text from your version control system. Define [OUTPUT_SCHEMA] as a strict JSON Schema that matches your downstream consumption format—for example, requiring fields like version, date, categories, and breaking_changes. Use [CONSTRAINTS] to add team-specific rules, such as linking to an issue tracker or enforcing a specific tone. [EXAMPLES] should contain one or two few-shot examples of correct output for your schema. Set [RISK_LEVEL] to high if the release note will be published to customers without human review; this should trigger an additional validation step in your harness. After generating the output, always validate it against your schema and run a factuality check by mapping each claim back to a specific line in the diff.

The Commit Diff to Release Note prompt is designed to be a single step inside a larger release automation harness. It takes a structured diff as input and returns a structured release note entry. The harness is responsible for providing the correct input, validating the output, and deciding what happens next. Do not treat this prompt as a standalone black box that always produces correct, publication-ready text. Instead, wrap it in a pipeline that controls input assembly, output verification, retry logic, and human approval gates before the release note reaches users.

Input assembly is the first critical step. The prompt expects a [COMMIT_DIFF] placeholder containing a unified diff of changes between two release tags or commits. The harness must generate this diff using git diff <previous_tag>..<current_tag> or an equivalent API call. Do not pass raw commit messages alone; the prompt needs the actual code changes to ground its output. If the diff exceeds the model's context window, the harness must split it into logical chunks (e.g., by file, directory, or subsystem) and run the prompt once per chunk, then merge the results. Include a [RELEASE_VERSION] placeholder with the target version string and a [PREVIOUS_RELEASE_NOTES] placeholder with the prior release's notes for continuity and tone calibration. The harness should also inject a [CONSTRAINTS] block specifying the output format (e.g., JSON with features, bug_fixes, breaking_changes arrays) and any team-specific style rules.

Output validation is mandatory before the release note is published. The prompt returns structured data, so the harness must parse the JSON and run a series of checks. First, validate the schema: every entry must have the required fields, and no field should contain placeholder text or unresolved tokens. Second, run a factuality check by comparing each claim in the release note against the source diff. A secondary LLM call or a deterministic grep for mentioned function names, error messages, or API endpoints can catch hallucinations. Third, run a deduplication check to ensure the same change is not listed in multiple categories. If validation fails, the harness should retry the prompt with the validation errors appended to the [CONSTRAINTS] block, up to a maximum of three retries. After three failures, escalate to a human reviewer with the raw diff, the failed output, and the specific validation errors.

Human approval and CI integration complete the harness. The validated release note should be written to a draft file in the repository (e.g., CHANGELOG.draft.md or a structured JSON artifact) and attached to a pull request or release ticket. Configure a CODEOWNERS rule or a manual approval step that requires a release manager or DevRel engineer to review the draft before it is merged and published. For fully automated pipelines, add an evaluation gate using a set of golden diffs with known-good release notes. If the prompt's output on these golden examples drifts in quality or format, block the release pipeline and flag the prompt for review. Never auto-publish release notes without either a human approval step or a proven, monitored evaluation gate that has been calibrated against your team's accuracy requirements.