sbt-gs-semver

SemVer plugin for Garrity Software projects. Typically used for library development.

• Usage
  • Adding the Plugin
  • Updating the Build File
  • Publishing a Release
• Supported Setting Keys
  • semVerSelected
  • semVerMajor
  • semVerCurrent
• Supported Command Line Properties
  • The release Property
  • The snapshot Property
• Supported Tasks
  • semVerInfo
• Complete Example

Usage

This is an auto plugin that provides setting keys for version values.

1. Add the plugin to your build.
2. Update your build file to leverage the calculated SemVer values.
3. Build releases using the -Drelease parameter.

Adding the Plugin

File: project/plugins.sbt

resolvers += "Garrity Software Releases" at "https://maven.garrity.co/gs"

addSbtPlugin("gs" % "sbt-gs-semver" % "0.1.0")

Updating the Build File

On any project within the build:

.settings(version := semVerSelected.value)
.settings(name := s"$ProjectName-v${semVerMajor.value}")

Publishing a Release

If the release property is set, a release build will be produced. The valid values for release are:

• major
• minor
• patch

sbt -Drelease=minor publish

Supported Setting Keys

These are available in build.sbt once the plugin is added.

semVerSelected

This setting should be used as the project version. Assign the value of this setting to the version setting:

lazy val `example` = project
  .in(file("."))
  .settings(version := semVerSelected.value)

semVerMajor

This setting should be used to calculate library names that are version-aware. This practice helps protect against binary compatibility issues stemming from different library versions existing as transitive dependencies.

lazy val `example` = project
  .in(file("."))
  .settings(version := semVerSelected.value)

semVerCurrent

Supported Command Line Properties

Properties are provided via -D parameters: -D<name>=<value>.

The release Property

Value may be any of: major, minor, patch. If this property is set, the build will calculate a semantic version by incrementing the selected version component. If this property is not defined, a pre-release build is assumed and the patch version is incremented.

The snapshot Property

Used to force a pre-release build. If -Dsnapshot=true is specified, the -SNAPSHOT suffix will be appended to the version.

Command Line Examples

Assume that the current version of the project is 1.2.3.

Release	Snapshot	semVerSelected	semVerMajor
		1.2.4-SNAPSHOT	1
	true	1.2.4-SNAPSHOT	1
patch		1.2.4	1
patch	true	1.2.4-SNAPSHOT	1
minor		1.3.0	1
minor	true	1.3.0-SNAPSHOT	1
major		2.0.0	2
major	true	2.0.0-SNAPSHOT	2

Supported Tasks

semVerInfo

Invoking sbt semVerInfo will emit diagnostic version information at the info log level via the SBT logger.

sbt -Drelease=minor -Dsnapshot=true semVerInfo
...
[info] [SemVer] Current: 0.1.0
[info] [SemVer] Selected: 0.2.0-SNAPSHOT
...

Complete Example

plugins.sbt

resolvers += "Garrity Software Releases" at "https://maven.garrity.co/gs"

addSbtPlugin("gs" % "sbt-gs-semver" % "0.1.0")

build.sbt

val scala3: String = "3.3.1"

ThisBuild / organizationName     := "garrity software"
ThisBuild / organization         := "gs"
ThisBuild / scalaVersion         := scala3
ThisBuild / versionScheme        := Some("semver-spec")

lazy val sharedSettings = Seq(
  scalaVersion := scala3,
  version      := semVerSelected.value
)

lazy val `gs-example` = project
  .in(file("."))
  .settings(sharedSettings)
  .settings(publishSettings)
  .settings(name := s"example-v${semVerMajor.value}")