168 lines
4.5 KiB
Markdown
168 lines
4.5 KiB
Markdown
# gs-semver-sbt-plugin
|
|
|
|
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" % "gs-semver-sbt-plugin" % "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
|
|
|
|
```
|
|
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" % "gs-semver-sbt-plugin" % "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 publishSettings = Seq(
|
|
publishTo := {
|
|
val repo = "https://maven.garrity.co/"
|
|
if (semVerSnapshot.value)
|
|
Some("Garrity Software Maven" at repo + "snapshots")
|
|
else
|
|
Some("Garrity Software Maven" at repo + "releases")
|
|
}
|
|
)
|
|
|
|
lazy val `gs-example` = project
|
|
.in(file("."))
|
|
.settings(sharedSettings)
|
|
.settings(publishSettings)
|
|
.settings(name := s"example-v${semVerMajor.value}")
|
|
```
|