Semantic Version Bump Recommendation Prompt

This prompt is designed for release engineers and CI/CD pipeline maintainers who need a consistent, automated method for determining the next semantic version number. The core job-to-be-done is translating a set of changes—represented as commit messages, code diffs, or structured change summaries—into a single version bump recommendation (major, minor, or patch) with clear, auditable reasoning. The ideal user is someone integrating this decision into an automated release workflow, where a human might still approve the final version but needs a reliable, rule-based starting point to eliminate manual guesswork and inconsistency. Required context includes the project's current version and a complete, accurate record of the changes since that version was tagged.

You should not use this prompt when the project does not follow semantic versioning (SemVer) rules, as the output will be meaningless or misleading. It is also inappropriate when you lack concrete change evidence, such as a full commit log or diff, because the model will be forced to hallucinate a recommendation. Furthermore, this prompt is not a replacement for business-level judgment about marketing version names (e.g., 'v2.0' as a branding milestone) or for decisions that must weigh customer-facing impact beyond the technical contract of an API. For high-risk releases, such as those in regulated infrastructure or with wide-breaking changes, the prompt's output should be treated as a strong recommendation that requires explicit human review and approval before a release is cut.

To get the most value, provide the prompt with structured input, such as a list of conventional commit messages or a summary of features, fixes, and breaking changes. The prompt will then apply the SemVer rules: a breaking change mandates a major bump, a new feature mandates a minor bump, and all other changes default to a patch bump. The next step after receiving the recommendation is to validate it against your own changelog and release notes, ensuring no breaking change was missed. Avoid using this prompt for pre-release or build metadata generation unless you explicitly include those rules in the [CONSTRAINTS] field, as the default logic focuses on the core major.minor.patch sequence.

This prompt template is designed to be pasted directly into your AI harness. It instructs the model to act as a release engineer, analyzing a structured change summary to recommend the next semantic version. The prompt enforces strict adherence to the SemVer 2.0.0 specification and requires the model to ground its recommendation in specific evidence from the input.

textCopy
You are a release engineer specializing in semantic versioning (SemVer 2.0.0). Your task is to analyze the provided change summary and recommend the next version number.

# INPUT
[CHANGE_SUMMARY]

# CURRENT VERSION
[CURRENT_VERSION]

# OUTPUT SCHEMA
You must respond with a single valid JSON object. Do not include any text outside the JSON block.
{
  "recommended_version": "string (the new semantic version, e.g., 1.5.2)",
  "bump_type": "MAJOR | MINOR | PATCH | PRE_RELEASE | BUILD",
  "rationale": "string (a concise explanation grounded in specific changes from the input)",
  "breaking_changes": ["list of strings describing each breaking change found"],
  "new_features": ["list of strings describing non-breaking new features"],
  "bug_fixes": ["list of strings describing backward-compatible bug fixes"]
}

# CONSTRAINTS
1. **Strict SemVer:** If any change is marked as BREAKING, you MUST recommend a MAJOR bump. If there are new, backward-compatible features, you MUST recommend a MINOR bump. If there are only backward-compatible bug fixes, you MUST recommend a PATCH bump.
2. **Pre-release Handling:** If the [CURRENT_VERSION] is a pre-release (e.g., 2.0.0-rc.1), recommend the next pre-release version (e.g., 2.0.0-rc.2) unless the input indicates a final release, in which case recommend the stable version (e.g., 2.0.0).
3. **Build Metadata:** Preserve or increment build metadata (e.g., +20240101) only if specified in the [CONSTRAINTS]. Otherwise, strip it from the recommendation.
4. **Evidence Grounding:** Every entry in `breaking_changes`, `new_features`, and `bug_fixes` must be directly traceable to a specific item in the [CHANGE_SUMMARY]. Do not invent or assume changes.
5. **Uncertainty:** If the [CHANGE_SUMMARY] is empty or ambiguous, set `bump_type` to "PATCH" as a safe default and state the assumption in the `rationale`.

To adapt this template, replace the [CHANGE_SUMMARY] and [CURRENT_VERSION] placeholders with real data. The [CHANGE_SUMMARY] should be a structured list of changes, ideally with each item tagged as BREAKING, FEATURE, or FIX. For high-risk releases, such as those for critical infrastructure or public APIs, you should add a [RISK_LEVEL] constraint and route the model's output to a human approval queue before any automated version bump is applied. Always validate the output JSON against the schema and log the rationale for auditability.

The semantic version bump recommendation prompt is designed to sit inside a release pipeline, not to be called in isolation. It expects structured input from prior change analysis steps—typically a commit diff, a list of merged PRs, or a breaking change detection report. The prompt should be invoked after change analysis but before the release is tagged. Its output is a version recommendation with rationale, which downstream systems can use to update package manifests, trigger changelog generation, or populate release metadata. Do not use this prompt on raw, unprocessed git logs; the input must already be filtered to the changes relevant to the upcoming release.

Wire the prompt into a pipeline stage that assembles the [CHANGE_SUMMARY] input from prior steps. For example, a CI job might run git log --oneline v1.2.3..HEAD, pass the output through a breaking change detection prompt, and then feed the structured results into this version bump prompt. Validate the output against a semver regex (^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$). If the output fails validation, retry once with a repair prompt that includes the validation error. If the second attempt also fails, escalate to a human reviewer. For high-risk releases—those touching authentication, payment, or data migration paths—always require human approval before the version bump is applied, regardless of validation success. Log the full prompt input, model response, validation result, and reviewer decision for auditability.

Model choice matters here. Use a model with strong instruction-following and structured output capabilities, such as Claude 3.5 Sonnet or GPT-4o, because the prompt requires precise reasoning about semver rules and edge cases. Avoid smaller or older models that may conflate minor and patch bumps or mishandle pre-release identifiers. If your pipeline runs in a constrained environment, consider caching the prompt prefix (the system instructions and semver rules) to reduce latency and cost. The output schema should be enforced via tool calling or structured output mode where available, rather than relying on free-text parsing. Finally, pair this prompt with a downstream verification step: after the version bump is applied, run a changelog accuracy prompt to confirm that all breaking changes, features, and fixes in the source diff are reflected in the release documentation.