API Changelog Generation Prompt from Diffs

This prompt is designed for developer relations engineers and API platform teams who need to convert raw OpenAPI or JSON Schema diffs into structured, human-readable changelogs. The core job-to-be-done is transforming a machine-readable specification delta into a versioned release document that developers can use to understand what changed, whether their integration will break, and exactly what code they need to modify. The ideal user has access to a diff between two API specification versions and needs to produce release notes organized by impact category—breaking, deprecated, added, fixed, and security—with migration guidance attached to each breaking or deprecated change.

Use this prompt when you have a concrete spec diff as input and need a consistent, categorized changelog that follows semantic versioning expectations. It is appropriate for CI/CD pipelines that generate release notes automatically on spec changes, for developer portal updates where changelogs must be accurate and complete, and for internal API governance workflows where platform teams need to communicate changes to consuming service teams. The prompt assumes the input diff is accurate and complete; it does not validate the diff itself or detect missing changes. It also assumes you have a target version number and release date to anchor the changelog. Do not use this prompt when the diff is incomplete, when you need to explain the business rationale behind changes, or when you are generating marketing-facing release announcements that require a different tone and level of technical detail.

This prompt is not a replacement for API review judgment. It classifies and describes changes but does not assess whether a breaking change was intentional, whether a deprecation window is sufficient, or whether migration guidance is safe. Always pair the generated changelog with human review for breaking changes, especially those affecting authentication, authorization, data integrity, or payment flows. The prompt also does not generate SDK migration code or update client libraries—it produces documentation that points developers toward the changes they need to make. For teams with multiple API surfaces, run this prompt per spec to keep changelogs scoped and avoid cross-contamination between unrelated services.

The following prompt template is designed to be dropped into your changelog generation pipeline. It expects a structured diff input, a target audience context, and an output schema that your documentation system can consume. Every placeholder is marked with square brackets and must be populated by your application before the prompt is sent to the model. Do not modify the core instruction structure unless you also update the corresponding eval assertions and validation logic.

textCopy
You are an API changelog generator for developer relations. Your task is to convert a structured API specification diff into a versioned, human-readable changelog organized by impact category.

## INPUT
[DIFF_INPUT]

## CONTEXT
- API Name: [API_NAME]
- Previous Version: [PREVIOUS_VERSION]
- New Version: [NEW_VERSION]
- Release Date: [RELEASE_DATE]
- Target Audience: [TARGET_AUDIENCE] (e.g., external developers, internal service teams, SDK maintainers)

## OUTPUT SCHEMA
Return a JSON object with the following structure:
{
  "changelog": {
    "api_name": "string",
    "previous_version": "string",
    "new_version": "string",
    "release_date": "string",
    "summary": "string (1-3 sentence plain-English summary of this release)",
    "categories": [
      {
        "impact": "breaking|deprecated|added|fixed|changed|security",
        "changes": [
          {
            "endpoint": "string (affected endpoint path or resource name)",
            "description": "string (what changed, in plain language)",
            "before": "string or null (previous behavior or payload snippet)",
            "after": "string or null (new behavior or payload snippet)",
            "migration_guidance": "string or null (actionable steps for affected consumers)",
            "affected_clients": ["string"] (list of client types or SDKs affected, empty array if unknown)
          }
        ]
      }
    ]
  }
}

## CONSTRAINTS
- Only include changes present in [DIFF_INPUT]. Do not invent or assume changes not listed.
- Classify each change into exactly one impact category. Use "breaking" for changes that will cause existing client code to fail without modification. Use "deprecated" for features still functional but scheduled for removal. Use "added" for net-new functionality. Use "fixed" for bug fixes. Use "changed" for non-breaking modifications. Use "security" for vulnerability fixes or security-related changes.
- If a change affects multiple endpoints, list it once per affected endpoint.
- Migration guidance must be specific and actionable. Do not write generic advice like "update your code."
- If the diff contains no changes in a category, omit that category from the output.
- If [DIFF_INPUT] is empty or unparseable, return {"error": "No parseable diff provided."}

## EXAMPLES
[FEW_SHOT_EXAMPLES]

## RISK LEVEL
[RISK_LEVEL] (one of: low, medium, high, critical)
- If RISK_LEVEL is "high" or "critical", flag any breaking change with an additional "urgent_action_required": true field and include a recommended communication channel (e.g., email, status page, direct outreach).

After copying this template, replace each placeholder with data from your pipeline. [DIFF_INPUT] should be a structured diff format your model understands—OpenAPI JSON diff, a unified text diff with context, or a pre-parsed change list. [FEW_SHOT_EXAMPLES] should contain 2-4 example input-output pairs that demonstrate correct categorization, especially for ambiguous cases like field additions that are additive versus field additions that are breaking due to strict client validation. [RISK_LEVEL] should be set by your CI/CD system based on the number of breaking changes detected or the blast radius of affected endpoints. Before deploying, run this prompt against a golden dataset of known diffs and verify that categorization accuracy exceeds your threshold, that no changes are dropped, and that migration guidance is non-empty for every breaking and deprecated change.

The API Changelog Generation Prompt from Diffs is designed to run as a post-diff step in a CI pipeline or as a developer CLI tool invoked after spec changes are committed. The primary input is a structured diff between two OpenAPI, GraphQL, or gRPC specification versions. The harness must preprocess raw git diff output into a format the model can reason over—typically a side-by-side summary of added, removed, and modified paths, operations, parameters, schemas, and enum values. Do not pass raw unified diffs directly; the model performs better when the diff is pre-parsed into a change inventory with explicit before/after values for each affected element.

Wire the prompt into an application by building a thin orchestration layer that: (1) parses the spec diff into a structured change list using a spec-aware tool like openapi-diff, graphql-inspector, or a custom buf breaking wrapper; (2) injects the change list into the [DIFF_INVENTORY] placeholder along with the [SPEC_TYPE], [VERSION_OLD], [VERSION_NEW], and [OUTPUT_FORMAT] variables; (3) calls the model with response_format set to json_object and a JSON Schema that enforces the expected changelog structure (arrays of breaking, deprecated, added, fixed, and changed entries, each with title, description, migration_guidance, affected_paths, and severity fields); (4) validates the output against that schema and retries once on validation failure with the error message appended to the prompt; (5) writes the validated changelog to a versioned file and posts it as a PR comment or release note draft. For high-risk API surfaces, add a human approval gate: the harness should create a draft changelog, flag any severity: critical entries, and require a platform team reviewer to approve before the changelog is published to external developer portals.

Model choice matters here. Use a model with strong structured output support and long-context reasoning for large specs—GPT-4o or Claude 3.5 Sonnet work well for OpenAPI specs up to ~5,000 lines. For larger specs, chunk the diff by endpoint group and run the prompt per chunk, then merge results with a deduplication pass. Log every generation with the input diff hash, model version, output validation status, and reviewer decision. This creates an audit trail for changelog accuracy disputes. Avoid running this prompt on every commit; trigger it only on spec file changes in designated paths (e.g., specs/**/*.yaml) and gate on PR merge to main to prevent changelog noise from work-in-progress branches.