Versioning

[rig].version is a semver string. The Hub uses it for ordering, rig hub update uses it for resolution, and consumers use it to pin.

When to bump

The rule of thumb: would an existing user need to do anything beyond rig hub update to keep the rig working? If yes, that's a major bump.

What counts as breaking

In rig terms, breaking means an existing install will fail rig doctor or stop working after rig hub update. Examples:

• A new required env var. (Existing users will see a gap.)
• A renamed env var (old one removed, new one required).
• A removed MCP server that other parts of the rig still expect.
• A [run].entrypoint change that breaks a documented command.
• A [package] change that drops a file an existing workflow depends on.

Adding a new optional env var, a new MCP server that doesn't replace anything, or a new skill is not breaking.

Pre-release

Use semver pre-release suffixes when you want to publish without claiming stability:

0.1.0-alpha.1
0.1.0-beta.2
1.0.0-rc.1

rig use will not pick a pre-release as "latest" unless explicitly requested with @version.

Pinning

Consumers can pin:

rig hub use hub:you/your-rig@1.2.0

rig hub update --check will tell them when a newer release exists; rig update won't move them to a major bump unless they re-use the new version explicitly.

Changelogs

Rig itself doesn't ship a changelog format. Include a CHANGELOG.md in your rig (it'll be included by default) so users can see what changed without diffing manifests.

See also

• Publish
• [rig] reference