dkduckkit.dev

API Versioning Decision Helper

Interactive SemVer: decide major, minor, or patch bumps with clear rationale for API changes.

Last updated: March 2026

TL;DR

Walk additive, deprecating, and breaking API edits to pick the correct SemVer bump with rationale your team can paste into changelogs.

Formula: Breaking change → major; backward-compatible feature → minor; fixes without API contract change → patch.

When to use this

  • Before publishing SDKs or public OpenAPI after a release train.
  • Aligning platform and product teams on consumer impact.

Related glossary

How the math works

How the math worksLaTeX model and TypeScript reference — same logic as the calculator on this page.

This describes the implementation behind the numbers as of 2026-03-26. It is engineering documentation, not legal or compliance advice.

Specification citation

Logic reflects our proprietary implementation of the following public specifications: Semantic Versioning 2.0.0.

This snippet represents the core logic of our proprietary calculation engine, verified against Semantic Versioning 2.0.0.

Model (LaTeX source)
SemVer bump selection (duckkit.dev rules)

Each selected change c has type t(c) ∈ { breaking, feature, fix }.

bump =
  major  if ∃c : t(c) = breaking
  minor  else if ∃c : t(c) = feature
  patch  otherwise

Matches SemVer precedence: incompatible API → MAJOR; backward-compatible additions → MINOR;
fixes without contract change → PATCH.
Reference implementation (TypeScript, excerpt from shipped modules)
// lib/api-versioning/decision-logic.ts
export function calculateBump(selectedIds: string[]): DecisionResult {
  if (selectedIds.length === 0) return { bump: 'none', ...RESULTS.none }

  const selected = CHANGES.filter((c) => selectedIds.includes(c.id))
  const hasBreaking = selected.some((c) => c.type === 'breaking')
  const hasFeature = selected.some((c) => c.type === 'feature')

  const bump = hasBreaking ? 'major' : hasFeature ? 'minor' : 'patch'
  return { bump, ...RESULTS[bump] }
}

No SemVer bump. Select one or more API changes below.

At a glance

Recommended bump
—

Breaking Changes

New Features

Bug Fixes & Maintenance

Recommendation

Select one or more changes above to get a versioning recommendation.

Methodology

Each checkbox maps to a change type (breaking, feature, or fix). With at least one selected, the bump is major if any breaking change is selected; otherwise minor if any feature is selected; otherwise patch (fixes only). With nothing selected, the result is none. This is an opinionated helper aligned with common SemVer practice — it does not parse your repository or diff OpenAPI specs.

Understanding Semantic Versioning (SemVer)

Semantic versioning (SemVer) is a versioning scheme that helps API developers communicate the impact of changes to their consumers. When you bump your API version, you signal whether existing clients need to update their code or can safely upgrade.

When to bump major version

A major version bump indicates breaking changes that make your API incompatible with previous versions. If you remove endpoints, rename fields, change response shapes, or modify authentication — existing consumers will need to update their integration. This is when you bump the major number (e.g., v1.0.0 → v2.0.0).

When to bump minor version

A minor version bump signals backward-compatible new functionality. Adding optional parameters, new endpoints, or optional response fields does not break existing clients. They can upgrade without code changes. Bump the minor number (e.g., v1.4.2 → v1.5.0).

When to bump patch version

A patch version bump is for backward-compatible bug fixes. Fixing incorrect behavior, improving performance, or updating documentation without changing the API contract qualifies as a patch. Bump the patch number (e.g., v1.4.2 → v1.4.3).

For the full specification, see semver.org.

SemVer vs calendar versioning

SemVer signals compatibility from version numbers; CalVer encodes release time. Public APIs usually pick SemVer so clients can reason about breaking changes—use this tool for SemVer decisions.

Copy-paste solution

## API change checklist (paste into PR)
- [ ] Breaking: removed/renamed fields or stricter validation → MAJOR
- [ ] Non-breaking new optional fields → MINOR
- [ ] Bugfix, same contract → PATCH
- [ ] Linked OpenAPI / JSON Schema diff attached

Related tools