A modular Scala 3 toolkit for intent-based versioning conforming to SemVer 2.0.0.

Cross-platform (JVM, Scala.js, Scala Native) with sbt integration, CLI tooling, and codec support.

Traditional versioning tools derive version numbers from repository history—counting commits since the last tag, appending distance suffixes, or inferring from branch patterns. This answers "how far are we from the last release?" but leaves the intended next version implicit.

version inverts this paradigm: developers declare the target version through commit message directives, and the system validates and enforces that intent. Snapshots represent pre-releases of the upcoming version, not post-release distances from a previous one.

Key properties:

• Explicit control — versioning intent declared in commit history
• Validation — target directives validated against regression rules
• Auditability — version decisions traceable through commits
• Determinism — identical repository state always produces identical versions

Note: Requires sbt 2.x. Not compatible with sbt 1.x.

Add to project/plugins.sbt:

addSbtPlugin("africa.shuwari" % "sbt-version" % "<version>")

The plugin automatically derives and sets version for all projects.

//> using dep "africa.shuwari::version::<version>"

import version.*

// Parse
val v = "2.1.0-rc.1+build.123".toVersion // Either[ParseError, Version]

// Construct
val release = Version(
  MajorVersion.fromUnsafe(1),
  MinorVersion.fromUnsafe(2),
  PatchNumber.fromUnsafe(3)
) // 1.2.3

// Operations
release.next[MinorVersion] // 1.3.0
release.as[Snapshot] // 1.2.3-SNAPSHOT
release.as[Alpha] // 1.2.3-alpha.1

Embed directives anywhere in commit messages to control versioning:

target: 2.5.0           # Set explicit target
version: major          # Increment major (1.2.3 → 2.0.0)
version: minor          # Increment minor (1.2.3 → 1.3.0)
version: patch          # Increment patch (1.2.3 → 1.2.4)

Standalone shorthands (requires non-empty text after colon):

breaking: Remove deprecated API     # Major increment
feat: Add caching support           # Minor increment
fix: Handle edge case               # Patch increment

See the documentation microsite for detailed documentation.

• Getting Started
• Core Library
• sbt Plugin
• CLI
• Version Resolution Specification

Apache 2.0