Semantic versioning

Mint uses strict release tags in the form vMAJOR.MINOR.PATCH, such as v2.4.1. Prerelease and build-metadata tags are not strict release tags for Mint's resolver or selection commands.

How the next version is chosen

The resolver evaluates commits since the highest reachable strict SemVer base tag. The strongest change wins.

Without a base, breaking changes start at v1.0.0, features at v0.1.0, and other changes at v0.0.1. Breaking changes increment major even for a v0.x.y base. There is no special pre-1.0 minor-bump exception.

For example, feat(GH-42): :sparkles: add preview environments triggers minor; fix(api)!: remove legacy response fields triggers major. A gitmoji in the description does not determine the bump.

Resolve without publishing

mint release resolve --commitish HEAD

Resolution reads Git history; it does not push tags, publish images, or deploy. If the target already has strict SemVer tags, it reuses the highest and reports already-tagged.

Fetch full history and tags in CI. Shallow history cannot reliably establish the base or evaluated range.

Component releases in one repository

A repository can release several components on independent version lines. Give each component a tag prefix and the paths it owns:

mint release resolve --tag-prefix backend/ --path backend
mint release resolve --tag-prefix frontend/ --path frontend --path shared/ui

• Tags take the form <prefix>vMAJOR.MINOR.PATCH, for example backend/v1.4.0. A prefix contains letters, digits, ., _, /, or - and must be safe in a Git ref.
• Each scope only sees its own tags. Unprefixed resolution ignores backend/… tags, and a backend/ scope ignores v… and frontend/… tags, so existing whole-repository releases keep working beside component releases.
• --path is a repeatable Git pathspec. Only commits that touch those paths count toward the bump, the commit count, and the release notes. A commit that touches two components counts for both.
• select-tag, tag, github, and publish accept --tag-prefix and reject tags outside the scope. publish also accepts --path and writes the bare X.Y.Z to the version file.
• In the GitHub Action, set tag-prefix and paths (one pathspec per line):

- uses: jamesonstone/mint@v1
  with:
    command: release-publish
    tag-prefix: backend/
    paths: |
      backend

Without a prefix or paths, behavior is unchanged.

To source-version a component on every default-branch push, point version-main at the component's schema 2 policy. Only first-parent commits that touch the component's paths receive <prefix>vX.Y.Z tags, and the policy's release-control files are treated as control-only:

mint release version-main --config .mint/backend.yaml --main-ref origin/main

In the Action, set command: release-version-main and version-config: .mint/backend.yaml. For a component, the outputs describe the target commit and add component_changed: false (with an empty version_tag) when that commit did not touch the component's paths, so the component's build job can skip instead of failing. Without --config, version-main versions every commit on one unprefixed line, as before. See Integrate Mint for component environment policies.

Source version versus deployed release

mint release version-main serially allocates one version for every untagged first-parent default-branch commit, oldest first. Controllers must use current authoritative main rather than an old triggering event SHA. Occupied tags, including isolated hotfix tags, are skipped by advancing patch until a free version is found.

Trusted release-control-only commits also receive a source identity, but do not become application build candidates or add noise to application release notes. Source versioning does not create a GitHub Release or prove artifact eligibility. A selected environment release may include several source versions since its last verified deployment.

Immutable tags

mint release tag creates or reuses an annotated tag at an exact source commit. A tag already pointing at that commit is reusable; one pointing elsewhere is a conflict. Mint never moves a conflicting tag.

Inspect the conflicting tag and source identities before retrying. Do not repoint a published version to repair a deployment. Correct or revert source and release a new version, or request a retained-artifact rollback.

Select an existing version

mint release select-tag --commitish HEAD

Without --requested-tag, Mint selects the highest strict SemVer tag on the exact target commit and fails if none exists. With --requested-tag v1.2.3, it validates the version syntax and returns that selection; this alone does not prove the requested artifact exists, matches the commit, or was deployed. Environment requests additionally require authenticated candidate/history evidence.

Hotfix version series

An isolated hotfix allocates the next unused patch in the verified deployed version's series. If that environment is on v1.2.3 while ordinary work has reached v1.3.0, the fix remains in v1.2.x; occupied patches are skipped. Merge the correction back into ordinary source so later releases keep it.