# sbt-gs-semver

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

- [Usage](#usage)
    - [Adding the Plugin](#adding-the-plugin)
    - [Updating the Build File](#updating-the-build-file)
    - [Publishing a Release](#publishing-a-release)
- [Supported Setting Keys](#supported-setting-keys)
    - [`semVerSelected`](#semverselected)
    - [`semVerMajor`](#semvermajor)
    - [`semVerCurrent`](#semvercurrent)
- [Supported Command Line Properties](#supported-command-line-properties)
    - [The `release` Property](#the-release-property)
    - [The `snapshot` Property](#the-snapshot-property)
- [Supported Tasks](#supported-tasks)
    - [`semVerInfo`](#semverinfo)
- [Complete Example](#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**
```scala
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:

```scala
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.

```scala
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` |
| --------- | --------- | ---------------- | ------------- |
| <not set> | <not set> | `1.2.4-SNAPSHOT` | `1`           |
| <not set> | `true`    | `1.2.4-SNAPSHOT` | `1`           |
| `patch`   | <not set> | `1.2.4`          | `1`           |
| `patch`   | `true`    | `1.2.4-SNAPSHOT` | `1`           |
| `minor`   | <not set> | `1.3.0`          | `1`           |
| `minor`   | `true`    | `1.3.0-SNAPSHOT` | `1`           |
| `major`   | <not set> | `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`

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

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

### `build.sbt`

```scala
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}")
```