# sbt-gs-calver

CalVer 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)
    - [`calVer`](#calVer)
- [Supported Command Line Properties](#supported-command-line-properties)
    - [The `release` Property](#the-release-property)
- [Supported Tasks](#supported-tasks)
    - [`calVerInfo`](#calverinfo)
- [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 CalVer 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-calver" % "0.1.0")
```

### Updating the Build File

On any project within the build:

```
.settings(version := calVerSelected.value)
```

### Publishing a Release

```
sbt -Drelease=true publish
```

## Supported Setting Keys

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

### `calVerSelected`

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 := calVerSelected.value)
```

### `calVerMajor`

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 := calVerSelected.value)
```

## Supported Command Line Properties

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

### The `release` Property

Value is either `true` or `false`. If this property is not set, `false` is
assumed. Releases are opt-in.

## Supported Tasks

### `calVerInfo`

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

```
sbt calVerInfo
...
[info] [CalVer] Version: 2024.1.18-eba621c
...
```

## Complete Example

### `plugins.sbt`

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

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

### `build.sbt`

```scala
val scala3: String = "3.3.1"

ThisBuild / organizationName     := "garrity software"
ThisBuild / organization         := "gs"
ThisBuild / scalaVersion         := scala3

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

lazy val `gs-example` = project
  .in(file("."))
  .settings(sharedSettings)
```