Versioning & releases

Soxom assigns SDK versions automatically by reading conventional commits from your Config Repository. You don’t edit version numbers by hand — you write descriptive commit messages and Soxom proposes the bump.

Two release types

A release moves in two stages:

1. Staging Release — Soxom opens a PR from next → main in each Staging Repository. The PR title proposes the next semver version; the body contains the auto-generated changelog. This is your chance to review.
2. Production Release — Once the Staging Release PR is merged, Soxom opens a PR in the Production Repository that copies the new main. Merging this PR creates the semver tag and (optionally) triggers registry publishing.

Both PRs are opened by Soxom, both are merged by you.

Version bump rules

Soxom inspects every conventional commit in the Config Repository since the last Production tag and picks the largest bump implied by any of them:

Commit type	Example	Bump
feat:	feat: add cursor pagination to /users	minor
fix:	fix: correct nullable on User.email	patch
perf:	perf: drop unused schema imports	patch
refactor:	refactor: rename internal helpers	patch
feat!: / fix!: / BREAKING CHANGE: footer	feat!: rename users.list params	major
chore:, docs:, test:, ci:, build:	docs: update README	none

If no commits since the last tag would trigger a bump, no Staging Release PR is opened.

Pre-1.0 behavior

While your SDK’s current version is below 1.0.0, Soxom follows the semver convention for unstable APIs: breaking changes bump the minor version instead of major. feat: still bumps the patch component.

Current version	feat:	fix:	breaking
0.x.y	0.x.(y+1)	0.x.(y+1)	0.(x+1).0
>= 1.0.0	x.(y+1).0	x.y.(z+1)	(x+1).0.0

Auto-generated changelog

The Staging Release PR body groups commits by type and links each one back to the Config Repository:

## v1.3.0

### Features
- feat: add cursor pagination to /users (#42)
- feat: support multipart uploads on /files (#44)

### Fixes
- fix: correct nullable on User.email (#43)

### Other
- refactor: rename internal helpers (#45)

This block is copied verbatim into the Production Release PR and, if you opt in, into a CHANGELOG.md commit on main.

Overriding the version manually

You can override the proposed bump in two ways:

• Edit the Staging Release PR title before merging. Soxom parses the version out of the title (e.g., Release v2.0.0) and uses that instead of the computed bump.
• Use the dashboard’s version override on the Project’s release page. This sets the next version explicitly and persists across re-runs of the release.

Caution

Lowering the version below the last published tag is not allowed. Registries reject duplicate or out-of-order versions, so Soxom enforces strictly increasing semver.

Worked example

Starting tag: v1.2.0. Since that tag, the Config Repository has:

feat: add streaming to /chat
fix: handle null in PaymentMethod.last4
docs: clarify retry policy
chore: bump openapi-generator

The largest bump implied is feat: → minor. Soxom opens a Staging Release PR titled Release v1.3.0 with this changelog:

## v1.3.0

### Features
- feat: add streaming to /chat

### Fixes
- fix: handle null in PaymentMethod.last4

docs: and chore: are omitted because they don’t trigger a bump. Merging the Staging Release PR and then the Production Release PR produces the v1.3.0 tag in the Production Repository.

Next steps

• Publishing to registries — what happens after the tag
• Production repository — where the tag lives
• Config repository — where the commits come from