Release Note Machine-Readable Changelog Generation Prompt

This prompt is for teams that need to produce structured, machine-readable changelog data from commit history and code diffs. It is designed for tool consumption, generating JSON or YAML output with semantic versioning, change categories, and parseable entries. Use this when your release pipeline requires a validated changelog artifact that downstream systems, dashboards, or API consumers can ingest without manual reformatting. The ideal user is a release engineer, platform developer, or DevRel engineer who owns the release automation pipeline and needs changelog data that conforms to a known schema like keep-a-changelog or a custom internal format.

This prompt assumes you have access to a structured diff, a list of merged pull requests, or a commit range. It works best when your commit history follows a consistent convention—such as Conventional Commits—or when you can provide pre-parsed change metadata alongside raw diffs. The output is not a polished, narrative release announcement. It is a data artifact: every entry is categorized, versioned, and ready for programmatic consumption. You should wire this prompt into a CI step that runs after merge to main, feeding it the commit range since the last tag, and then validate the output against your changelog schema before publishing the artifact.

Do not use this prompt when your primary goal is customer-facing narrative polish, marketing framing, or executive summaries. It will not produce benefit-oriented feature descriptions or tone-adapted prose. For those needs, pair this prompt's structured output with a separate summarization step, or use a dedicated user-facing release summary prompt. Also avoid this prompt when your commit history is unstructured, lacks clear change categorization, or contains large volumes of irrelevant noise—without pre-filtering, the output quality will degrade. If your release process requires human approval before publication, treat this prompt as the first stage in a pipeline that routes the structured changelog through a review and sign-off workflow before distribution.

This section provides a complete, copy-ready prompt template that you can adapt for your release pipeline. The template is designed to take structured commit history and diff data as input and produce a validated, machine-readable changelog in JSON or YAML format. It uses square-bracket placeholders for all variable inputs, allowing you to inject your own data, schema definitions, and constraints without modifying the core instruction logic. The prompt enforces semantic versioning rules, change categorization, and schema compliance, making it suitable for direct integration into CI/CD systems or release automation workflows.

codeCopy
You are a precise changelog generation engine. Your output must be a valid, machine-readable changelog object that strictly conforms to the provided schema.

## INPUT DATA
Commit History:
[COMMIT_HISTORY]

Diff Summary:
[DIFF_SUMMARY]

## OUTPUT SCHEMA
You must produce a single JSON object matching this exact structure:
[OUTPUT_SCHEMA]

## CONSTRAINTS
- Categorize every change into exactly one of: `Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, `Security`.
- Determine the semantic version bump (`major`, `minor`, `patch`) based on the changes. A breaking change requires a `major` bump. A new feature requires a `minor` bump. All other changes require a `patch` bump.
- For each entry, include a `description` that is a single, self-contained sentence explaining the change from a user's or developer's perspective.
- If a commit fixes a known issue, include the issue reference in the `references` array.
- If no changes of a certain category exist, omit that category key entirely from the output.
- Do not include any text outside the JSON object.

## VERSION FORMAT
Follow [VERSION_FORMAT] strictly. The `version` field must be the recommended next version string.

## EXAMPLES
[EXAMPLES]

## RISK LEVEL
[RISK_LEVEL]

To adapt this template, replace each square-bracket placeholder with your specific data and requirements. [COMMIT_HISTORY] should contain a structured list of commits with messages, authors, and hashes. [DIFF_SUMMARY] should be a concise summary of the aggregated code changes, focusing on functional impact rather than line-by-line diffs. [OUTPUT_SCHEMA] must be a valid JSON Schema or a detailed structural description of your desired changelog format. [VERSION_FORMAT] should specify your versioning rules, such as "SemVer 2.0.0" or a custom format. [EXAMPLES] should include one or two few-shot examples of correct input-output pairs to guide the model. [RISK_LEVEL] should be set to high if the changelog will be published to external users, triggering the need for downstream validation and human review. After copying the template, wire it into your application with a JSON validator, a retry mechanism for malformed output, and a diff-based factuality check to catch hallucinated entries before publication.

This prompt is designed to be called programmatically, not pasted into a chat window. The primary integration point is a CI/CD pipeline step that runs after commits are tagged or a release branch is cut. The harness must supply structured inputs—typically a git log between two refs, a semantic version bump recommendation, and a target output schema—and then validate the model's JSON or YAML response before it ever reaches a changelog file or API consumer. Treat the prompt as a function with a strict contract: garbage in, garbage out, but also valid-looking JSON out that might still contain hallucinated entries.

Start by assembling the [COMMIT_HISTORY] input. Use git log <previous_tag>..<new_tag> --pretty=format:'%h %s (%an, %ad)' --date=short to produce a compact, parseable history. Pipe this into the prompt along with [VERSION_BUMP] (major, minor, patch), [PREVIOUS_VERSION], and [NEW_VERSION]. The [OUTPUT_SCHEMA] placeholder should contain a JSON Schema or a Keep a Changelog specification block that defines required fields: version, date, added, changed, deprecated, removed, fixed, security. For teams using Conventional Commits, also pass a [COMMIT_CONVENTION] block that maps prefixes to changelog categories. After the model responds, run a schema validator (e.g., ajv for JSON Schema, yamllint plus a custom schema check for YAML) before writing the output. If validation fails, retry once with the validation errors appended to the prompt as [PREVIOUS_ERRORS]. If the second attempt also fails, escalate to a human release manager and log the raw response for debugging.

Model choice matters here. Use a model with strong JSON mode or structured output support (e.g., GPT-4o with response_format: { type: 'json_object' }, Claude with tool-use forcing a typed output, or a fine-tuned open-weight model if you have sufficient training data). Avoid models that routinely inject markdown fences or explanatory text around structured output. Set temperature to 0 or near-zero to maximize determinism. For high-risk releases (major version bumps, security advisories), add a human approval gate: the pipeline should post the generated changelog as a draft PR comment and require a maintainer to approve before merging. Log every generation attempt—input hash, model, latency, validation result, and final output—so you can trace regressions when the prompt or model version changes.

The most common failure mode is hallucinated entries: the model invents a change that doesn't appear in the commit history. Mitigate this with a post-generation factuality check. After schema validation passes, run a second prompt (the Release Note Hallucination and Factuality Check Prompt from this pillar) that maps each changelog entry back to a specific commit hash. If any entry lacks a grounded commit, flag it for removal or human review. A cheaper alternative is a deterministic check: extract all commit hashes from the input, extract all referenced hashes from the output, and diff them. Entries without matching hashes are suspect. For teams with stricter requirements, embed this verification as a CI gate that blocks the release if hallucination is detected.

Finally, wire the validated output into your release artifacts. Write the JSON to a CHANGELOG.json file in the repository root, append a Markdown-formatted version to CHANGELOG.md using a template that matches Keep a Changelog conventions, and publish the structured data to an internal API or developer portal. Avoid the temptation to let the model generate the Markdown directly—generate the structured JSON first, validate it, then use a deterministic template to render Markdown. This separation ensures that downstream consumers (RSS feeds, Slack bots, documentation sites) always receive consistent, validated data, and it isolates formatting bugs from content bugs.