Usage

This page covers the two main versioning commands: changeset (create) and version (consume).

---

Creating changesets

Command

contractual changeset [--no-interactive] [--empty]

How it works

contractual changeset reads the diff between current specs and the last snapshot and opens an interactive prompt to describe changes and confirm the bump type (major, minor, or patch). The result is a Markdown file written to .contractual/changesets/.

Interactive mode (default): Displays detected changes, pre-fills a suggested bump type, and allows editing the summary before writing the file.

Non-interactive mode (--no-interactive): Auto-generates the changeset using the highest detected bump type. Use this in CI pipelines.

Empty changesets (--empty): Creates a changeset with no associated spec changes. Useful for changelog-only updates.

Options

Flag	Description	Default
--no-interactive	Skip the interactive prompt and auto-generate	Off
--empty	Create a changeset with no detected changes	Off

Examples

Interactive changeset creation

terminal

$ contractual changeset

Detected changes in payments-api (openapi):
✖  [breaking]      DELETE /v1/charges/{id}  Endpoint removed
✔  [non-breaking]  GET /v1/charges          Response field `metadata` added

? Bump type for payments-api: (major)
? Summary: Remove deprecated DELETE /v1/charges/{id} endpoint and add metadata field

Wrote .contractual/changesets/fuzzy-lion-dances.md

Non-interactive mode for CI

terminal

$ contractual changeset --no-interactive

Auto-generating changeset for detected changes...

payments-api: major bump detected (breaking changes found)

Wrote .contractual/changesets/silver-hawk-runs.md

Create an empty changeset

terminal

$ contractual changeset --empty

? Bump type: (patch)
? Summary: Update changelog with maintainer notes

Wrote .contractual/changesets/brave-wolf-leaps.md

---

Consuming changesets

Command

contractual version [--dry-run]

How it works

contractual version is the release command. It reads every changeset file in .contractual/changesets/, flattens their bump types (highest wins per contract), then:

1. Resolves bump types. For each contract, the highest bump across all pending changesets wins: major > minor > patch.
2. Updates versions. Writes new version numbers to .contractual/versions.json.
3. Snapshots specs. Copies the current state of each spec into .contractual/snapshots/ tagged with the new version.
4. Generates changelog. Appends a new entry to CHANGELOG.md grouped by contract and bump type.
5. Deletes consumed changesets. Removes the processed files from .contractual/changesets/.

Options

Flag	Description	Default
--dry-run	Preview without writing any files	Off

Examples

Apply all pending changesets

terminal

$ contractual version

Reading changesets...
fuzzy-lion-dances.md   →  payments-api  major
silver-hawk-runs.md    →  user-schema   minor

Resolved bump types:
payments-api   1.4.2  →  2.0.0  (major)
user-schema    0.9.1  →  0.10.0 (minor)

Snapshotting specs...
✔  .contractual/snapshots/payments-api@2.0.0.yaml
✔  .contractual/snapshots/user-schema@0.10.0.json

Updated .contractual/versions.json
Updated CHANGELOG.md
Deleted 2 changeset file(s)

Done. Commit these changes to complete the release.

Dry run to preview changes

terminal

$ contractual version --dry-run

[dry-run] Reading changesets...
fuzzy-lion-dances.md   →  payments-api  major
silver-hawk-runs.md    →  user-schema   minor

[dry-run] Resolved bump types:
payments-api   1.4.2  →  2.0.0  (major)
user-schema    0.9.1  →  0.10.0 (minor)

[dry-run] No files were written.

---

The full workflow

Step by step

1. PR opened with a spec change

The GitHub Action runs contractual breaking to compare the modified spec against the latest snapshot.

2. Changeset generated

Based on detected changes, Contractual creates a changeset file and commits it to the PR branch.

3. Developer reviews the changeset

The PR comment shows a diff table. If the developer disagrees with the classification, the changeset frontmatter is edited directly.

4. PR merges

The changeset file lands on main alongside the spec change.

5. contractual version runs

The GitHub Action runs contractual version, which bumps versions, creates snapshots, updates the changelog, and deletes consumed changesets.

6. Version Contracts PR opened

The Action opens a pull request with all version bumps. Merging this PR is the release.

---

Multiple changesets: highest bump wins

If multiple changesets land on main before contractual version runs, Contractual takes the highest bump for each contract:

fuzzy-lion-dances.md:   orders-api: minor
silver-hawk-runs.md:    orders-api: patch, order-schema: minor
brave-wolf-leaps.md:    orders-api: major

Result: orders-api gets a major bump. order-schema gets a minor bump.

---

Overriding auto-detected classifications

If auto-detection classifies a change incorrectly, edit the frontmatter directly:

Before (auto-generated):

---
"orders-api": major
---

Removed field `internal_trace_id` from Order response.

After (corrected):

---
"orders-api": patch
---

Removed the internal `internal_trace_id` field from the Order response. This
field was never documented and no external consumers reference it.

Contractual uses the value in the file at contractual version time. It does not re-run detection or override edits.

Tip

Update the markdown body to explain why the classification was overridden. This text appears in the changelog.

---

Exit codes

contractual changeset

Code	Meaning
0	Changeset file created successfully
2	Configuration error

contractual version

Code	Meaning
0	Versions bumped successfully (or --dry-run completed)
2	Configuration error, malformed changeset, or no changesets found

---

Next steps

• Overview: The changeset model explained
• Changeset Format: Full file format reference
• GitHub Action: Automate the workflow