• Stars
    star
    640
  • Rank 68,966 (Top 2 %)
  • Language
    Scala
  • License
    Apache License 2.0
  • Created almost 13 years ago
  • Updated 3 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

A release plugin for sbt

sbt-release

This sbt plugin provides a customizable release process that you can add to your project.

sbt-release Scala version support

Notice: This README contains information for the latest release. Please refer to the documents for a specific version by looking up the respective tag.

Requirements

  • sbt 1.x
  • The version of the project should follow the semantic versioning scheme on semver.org with the following additions:
    • The minor and bugfix (and beyond) part of the version are optional.
    • There is no limit to the number of subversions you may have.
    • The appendix after the bugfix part must be alphanumeric ([0-9a-zA-Z]) but may also contain dash characters -.
    • These are all valid version numbers:
      • 1.2.3
      • 1.2.3-SNAPSHOT
      • 1.2beta1
      • 1.2-beta.1
      • 1.2
      • 1
      • 1-BETA17
      • 1.2.3.4.5
      • 1.2.3.4.5-SNAPSHOT
  • A publish repository configured. (Required only for the default release process. See further below for release process customizations.)
  • git [optional]

Usage

Add the following lines to ./project/plugins.sbt. See the section Using Plugins in the sbt website for more information.

addSbtPlugin("com.github.sbt" % "sbt-release" % "1.3.0")

version.sbt

Since the build definition is actual Scala code, it's not as straight forward to change something in the middle of it as it is with an XML definition.

For this reason, sbt-release won't ever touch your build definition files, but instead writes the new release or development version to a file defined by the setting releaseVersionFile, which is set to file("version.sbt") by default and points to $PROJECT_ROOT/version.sbt.

By default the version is set on the build level (using ThisBuild / version). This behavior can be controlled by setting releaseUseGlobalVersion to false, after which a version like version := "1.2.3" will be written to version.sbt.

Release Process

The default release process consists of the following tasks:

  1. Check that the working directory is a git repository and the repository has no outstanding changes. Also prints the hash of the last commit to the console.
  2. If there are any snapshot dependencies, ask the user whether to continue or not (default: no).
  3. Ask the user for the release version and the next development version. Sensible defaults are provided.
  4. Run clean.
  5. Run test:test, if any test fails, the release process is aborted.
  6. Write ThisBuild / version := "$releaseVersion" to the file version.sbt and also apply this setting to the current build state.
  7. Commit the changes in version.sbt.
  8. Tag the previous commit with v$version (eg. v1.2, v1.2.3).
  9. Run publish.
  10. Write ThisBuild / version := "nextVersion" to the file version.sbt and also apply this setting to the current build state.
  11. Commit the changes in version.sbt.

In case of a failure of a task, the release process is aborted.

Non-interactive release

You can run a non-interactive release by providing the argument with-defaults (tab completion works) to the release command.

For all interactions, the following default value will be chosen:

  • Continue with snapshots dependencies: no
  • Release Version: current version without the qualifier (eg. 1.2-SNAPSHOT -> 1.2)
  • Next Version: increase the minor version segment of the current version and set the qualifier to '-SNAPSHOT' (eg. 1.2.1-SNAPSHOT -> 1.3.0-SNAPSHOT)
  • VCS tag: default is abort if the tag already exists. It is possible to override the answer to VCS by default-tag-exists-answer with one of:
    • o override
    • k do not overwrite
    • a abort (default)
    • <tag-name> an explicit custom tag name (e.g. 1.2-M3)
  • VCS push:
    • Abort if no remote tracking branch is set up.
    • Abort if remote tracking branch cannot be checked (eg. via git fetch).
    • Abort if the remote tracking branch has unmerged commits.

Set release version and next version as command arguments

You can set the release version using the argument release-version and next version with next-version.

Example:

release release-version 1.0.99 next-version 1.2.0-SNAPSHOT

Skipping tests

For that emergency release at 2am on a Sunday, you can optionally avoid running any tests by providing the skip-tests argument to the release command.

Cross building during a release

Since version 0.7, sbt-release comes with built-in support for cross building and cross publishing. A cross release can be triggered in two ways:

  1. via the setting releaseCrossBuild (by default set to false)

  2. by using the option cross for the release command

    > release cross with-defaults

Combining both ways of steering a cross release, it is possible to generally disable automatic detection of cross release by using releaseCrossBuild := false and running release cross.

Of the predefined release steps, the clean, test, and publish release steps are set up for cross building.

A cross release behaves analogous to using the + command:

  1. If no crossScalaVersions are set, then running release or release cross will not trigger a cross release (i.e. run the release with the scala version specified in the setting scalaVersion).
  2. If the crossScalaVersions setting is set, then only these scala versions will be used. Make sure to include the regular/default scalaVersion in the crossScalaVersions setting as well. Note that setting running release cross on a root project with crossScalaVersions set to Nil will not release anything.

In the section Customizing the release process we take a look at how to define a ReleaseStep to participate in a cross build.

Versioning Strategies

As of version 0.8, sbt-release comes with several strategies for computing the next snapshot version via the releaseVersionBump setting. These strategies are defined in sbtrelease.Version.Bump. By default, the Next strategy is used:

  • Major: always bumps the major part of the version
  • Minor: always bumps the minor part of the version
  • Bugfix: always bumps the bugfix part of the version
  • Nano: always bumps the nano part of the version
  • Next (default): bumps the last version part, including the qualifier (e.g. 0.17 -> 0.18, 0.11.7 -> 0.11.8, 3.22.3.4.91 -> 3.22.3.4.92, 1.0.0-RC1 -> 1.0.0-RC2)
  • NextStable: bumps exactly like Next except that any prerelease qualifier is excluded (e.g. 1.0.0-RC1 -> 1.0.0)

Users can set their preferred versioning strategy in build.sbt as follows:

releaseVersionBump := sbtrelease.Version.Bump.Major

Default Versioning

The default settings make use of the helper class Version that ships with sbt-release.

releaseVersion: The current version in version.sbt, without the "-SNAPSHOT" ending. So, if version.sbt contains 1.0.0-SNAPSHOT, the release version will be set to 1.0.0.

releaseNextVersion: The "bumped" version according to the versioning strategy (explained above), including the -SNAPSHOT ending. So, if releaseVersion is 1.0.0, releaseNextVersion will be 1.0.1-SNAPSHOT.

Custom Versioning

sbt-release comes with two settings for deriving the release version and the next development version from a given version.

These derived versions are used for the suggestions/defaults in the prompt and for non-interactive releases.

Let's take a look at the types:

val releaseVersion     : TaskKey[String => String]
val releaseNextVersion : TaskKey[String => String]

If you want to customize the versioning, keep the following in mind:

  • releaseVersion

    • input: the current development version
    • output: the release version
  • releaseNextVersion

    • input: the release version (either automatically 'chosen' in a non-interactive build or from user input)
    • output: the next development version

Custom VCS messages

sbt-release has built in support to commit/push to Git, Mercurial and Subversion repositories. The messages for the tag and the commits can be customized to your needs with these settings:

val releaseTagComment        : TaskKey[String]
val releaseCommitMessage     : TaskKey[String]
val releaseNextCommitMessage : TaskKey[String]

// defaults
releaseTagComment        := s"Releasing ${(ThisBuild / version).value}",
releaseCommitMessage     := s"Setting version to ${(ThisBuild / version).value}",
releaseNextCommitMessage := s"Setting version to ${(ThisBuild / version).value}",

Publishing signed releases

SBT is able to publish signed releases using the sbt-pgp plugin.

After setting that up for your project, you can then tell sbt-release to use it by setting the releasePublishArtifactsAction key:

releasePublishArtifactsAction := PgpKeys.publishSigned.value

Customizing the release process

Not all releases are created equal

The release process can be customized to the project's needs.

  • Not using Git? Then rip it out.
  • Want to check for the existence of release notes at the start of the release and then publish it with posterous-sbt at the end? Just add the release step.

The release process is defined by State transformation functions (State => State), for which sbt-release defines this case class:

case class ReleaseStep (
  action: State => State,
  check: State => State = identity,
  enableCrossBuild: Boolean = false
)

The function action is used to perform the actual release step. Additionally, each release step can provide a check function that is run at the beginning of the release and can be used to prevent the release from running because of an unsatisfied invariant (i.e. the release step for publishing artifacts checks that publishTo is properly set up). The property enableCrossBuild tells sbt-release whether or not a particular ReleaseStep needs to be executed for the specified crossScalaVersions.

The sequence of ReleaseSteps that make up the release process is stored in the setting releaseProcess: SettingKey[Seq[ReleaseStep]].

The state transformations functions used in sbt-release are the same as the action/body part of a no-argument command. You can read more about building commands in the sbt website.

Release Steps

There are basically 2 ways to creating a new ReleaseStep:

Defining your own release steps

You can define your own state tansformation functions, just like sbt-release does, for example:

val checkOrganization = ReleaseStep(action = st => {
  // extract the build state
  val extracted = Project.extract(st)
  // retrieve the value of the organization SettingKey
  val org = extracted.get(Keys.organization)

  if (org.startsWith("com.acme"))
    sys.error("Hey, no need to release a toy project!")

  st
})

We will later see how to let this release step participate in the release process.

Reusing already defined tasks

Sometimes you just want to run an existing task or command. This is especially useful if the task raises an error in case something went wrong and therefore interrupts the release process.

sbt-release comes with a few convenience functions for converting tasks and commands to release steps:

  • releaseStepTask - Run an individual task. Does not aggregate builds.
  • releaseStepTaskAggregated - Run an aggregated task.
  • releaseStepInputTask - Run an input task, optionally taking the input to pass to it.
  • releaseStepCommand - Run a command.

For example:

releaseProcess := Seq[ReleaseStep](
  releaseStepInputTask(testOnly, " com.example.MyTest"),
  releaseStepInputTask(scripted),
  releaseStepTask(publish in subproject),
  releaseStepCommand("sonatypeRelease")
)

I highly recommend to make yourself familiar with the State API before you continue your journey to a fully customized release process.

Can we finally customize that release process, please?

Yes, and as a start, let's take a look at the default definition of releaseProcess:

The default release process

import ReleaseTransformations._

// ...

releaseProcess := Seq[ReleaseStep](
  checkSnapshotDependencies,              // : ReleaseStep
  inquireVersions,                        // : ReleaseStep
  runClean,                               // : ReleaseStep
  runTest,                                // : ReleaseStep
  setReleaseVersion,                      // : ReleaseStep
  commitReleaseVersion,                   // : ReleaseStep, performs the initial git checks
  tagRelease,                             // : ReleaseStep
  publishArtifacts,                       // : ReleaseStep, checks whether `publishTo` is properly set up
  setNextVersion,                         // : ReleaseStep
  commitNextVersion,                      // : ReleaseStep
  pushChanges                             // : ReleaseStep, also checks that an upstream branch is properly configured
)

The names of the individual steps of the release process are pretty much self-describing. Notice how we can just reuse the publish task by utilizing the releaseTask helper function, but keep in mind that it needs to be properly scoped (more info on Scopes).

Note, the commitReleaseVersion step requires that the working directory has no untracked files by default. It will abort the release in this case. You may disable this check by setting the releaseIgnoreUntrackedFiles key to true.

No Git, and no toy projects!

Let's modify the previous release process and remove the Git related steps, who uses that anyway.

import ReleaseTransformations._

// ...

ReleaseKeys.releaseProcess := Seq[ReleaseStep](
  checkOrganization,                // Look Ma', my own release step!
  checkSnapshotDependencies,
  inquireVersions,
  runTest,
  setReleaseVersion,
  publishArtifacts,
  setNextVersion
)

Overall, the process stayed pretty much the same:

  • The Git related steps were left out.
  • Our checkOrganization task was added in the beginning, just to be sure this is a serious project.

Release notes anyone?

Now let's also add steps for posterous-sbt:

import posterous.Publish._
import ReleaseTransformations._

// ...

val publishReleaseNotes = (ref: ProjectRef) => ReleaseStep(
  check  = releaseStepTaskAggregated(check in Posterous in ref),   // upfront check
  action = releaseStepTaskAggregated(publish in Posterous in ref) // publish release notes
)

// ...

ReleaseKeys.releaseProcess <<= thisProjectRef apply { ref =>
  import ReleaseStateTransformations._
  Seq[ReleaseStep](
    checkOrganization,
    checkSnapshotDependencies,
    inquireVersions,
    runTest,
    setReleaseVersion,
    publishArtifacts,
    publishReleaseNotes(ref) // we need to forward `thisProjectRef` for proper scoping of the underlying tasks
    setNextVersion
  )
}

The check part of the release step is run at the start, to make sure we have everything set up to post the release notes later on. After publishing the actual build artifacts, we also publish the release notes.

Credits

Thank you, Jason and Mark, for your feedback and ideas.

Contributors

Johannes Rudolph, Espen Wiborg, Eric Bowman, Petteri Valkonen, Gary Coady, Alexey Alekhin, Andrew Gustafson, Paul Davies, Stanislav Savulchik, Tim Van Laer, Lars Hupel

License

Copyright (c) 2011-2014 Gerolf Seitz

Published under the Apache License 2.0

More Repositories

1

sbt

sbt, the interactive build tool
Scala
4,685
star
2

sbt-native-packager

sbt Native Packager
Scala
1,590
star
3

sbt-dependency-graph

sbt plugin to create a dependency graph for your project
Scala
1,241
star
4

sbt-jmh

"Trust no one, bench everything." - sbt plugin for JMH (Java Microbenchmark Harness)
Scala
783
star
5

sbt-eclipse

Plugin for sbt to create Eclipse project definitions
Scala
719
star
6

sbt-buildinfo

I know this because build.sbt knows this.
Scala
546
star
7

sbt-web

Library for building sbt plugins for the web
Scala
366
star
8

sbt-git

A git plugin for sbt
Scala
343
star
9

zinc

Scala incremental compiler library, used by sbt and other build tools
Scala
328
star
10

docker-sbt

Official sbt docker images
Dockerfile
313
star
11

sbt-dynver

An sbt plugin to dynamically set your version from git
Scala
297
star
12

sbt-ci-release

sbt plugin to automate Sonatype releases from GitHub Actions
Scala
278
star
13

sbt-onejar

Packages your project using One-JAR™
Scala
267
star
14

sbt-scalariform

sbt plugin adding support for source code formatting using Scalariform
Scala
258
star
15

sbt-fresh

sbt-plugin to create an opinionated fresh sbt project
Scala
233
star
16

sbt-github-actions

An sbt plugin which makes it easier to build with GitHub Actions
Scala
194
star
17

sbt-header

sbt-header is an sbt plugin for creating file headers, e.g. copyright headers
Scala
186
star
18

sbt-bintray

fresh packages delivered from your sbt console
Scala
179
star
19

sbt-protobuf

sbt plugin for compiling protobuf files
Scala
174
star
20

sbt-site

Site generation for sbt
Scala
173
star
21

sbt-start-script

SBT Plugin to create a "start" script to run the program
Scala
144
star
22

sbt-pgp

PGP plugin for sbt
Scala
141
star
23

sbt-groll

sbt plugin to roll the Git history
Scala
133
star
24

junit-interface

Implementation of sbt's test interface for JUnit
Java
132
star
25

sbt-unidoc

sbt plugin to create a unified Scaladoc or Javadoc API document across multiple subprojects.
Scala
124
star
26

sbt-jni

SBT Plugin to ease working with JNI
Scala
123
star
27

sbt-jacoco

an sbt plugin for JaCoCo Code Coverage
Scala
123
star
28

sbt-projectmatrix

Scala
118
star
29

sbt-boilerplate

sbt plugin for generating scala.Tuple/Function related boilerplate code
Scala
109
star
30

sbt-proguard

Proguard sbt plugin
Scala
98
star
31

sbt-atmos

sbt plugin for running Typesafe Console in development
Scala
98
star
32

sbt-launcher-package

Packaging for sbt so you can run it.
Scala
89
star
33

sbt-dirty-money

clean Ivy2 cache
Scala
88
star
34

sbt-license-report

Report on licenses used in an sbt project.
Scala
86
star
35

website

The source for scala-sbt.org
Scala
77
star
36

sbt-doge

sbt plugin to aggregate tasks across subprojects and their crossScalaVersions
Scala
77
star
37

sbt-pom-reader

Translates xml -> awesome. Maven-ish support for sbt.
Scala
76
star
38

sbt-remote-control

Create and manage sbt process using unicorns and forks
Scala
74
star
39

sbt-aspectj

AspectJ sbt plugin
Scala
72
star
40

sbt-scalabuff

SBT plugin which generate case classes and support for serialization from Google Protocol Buffer definitions using ScalaBuff
Scala
72
star
41

contraband

http://www.scala-sbt.org/contraband/
Scala
67
star
42

sbt-s3

sbt-s3 is a simple sbt plugin to manipulate objects on Amazon S3
Scala
63
star
43

sbt-multi-jvm

Multi-JVM testing in sbt
Scala
56
star
44

sbt-javaagent

sbt plugin for adding java agents to projects
Scala
53
star
45

sbt-paradox-material-theme

Material Design theme for Paradox
StringTemplate
51
star
46

sbt-cpd

Copy & Paste Detector plugin using PMD for sbt.
Scala
48
star
47

sbt-osgi

sbt plugin for creating OSGi bundles
Scala
47
star
48

sbt-man

Looks up scaladoc.
Scala
46
star
49

sbt-findbugs

FindBugs static analysis plugin for sbt.
Scala
46
star
50

librarymanagement

librarymanagement module for sbt
Scala
44
star
51

sbt-less

Scala
42
star
52

ipcsocket

IPC: Unix Domain Socket and Windows Named Pipes for Java
Java
42
star
53

launcher

The sbt launcher as its own project. Can launch any ivy/maven published project with a main class, with some fancy features.
Scala
41
star
54

io

IO module for sbt
Scala
40
star
55

sbt-js-engine

Support for sbt plugins that use JavaScript
Scala
40
star
56

sbt-autoversion

Scala
36
star
57

sbt-avro

sbt plugin for compiling Avro schemas, similar to sbt-protobuf
Scala
32
star
58

sbt-digest

sbt-web plugin for checksum files
Scala
32
star
59

sbt-jupiter-interface

Implementation of SBT's test interface for JUnit Jupiter
Java
31
star
60

sbt-slash

unified slash syntax for both shell and build.sbt
Scala
29
star
61

sbt-java-formatter

An sbt plugin for formating Java code
Scala
28
star
62

sbt-gzip

sbt-web plugin for gzipping assets
Scala
25
star
63

sbt-unique-version

emulates Maven's uniqueVersion snapshots
Scala
24
star
64

sbt-pull-request-validator

Plugin that optimizes pull request validation to only validate sub projects that have changed
Scala
24
star
65

sbt.github.com

See https://github.com/sbt/website for the source
HTML
22
star
66

sbt-duplicates-finder

Find classes and resources conflicts in your build
Scala
22
star
67

sbt-autoplugin.g8

giter8 template for sbt 0.13.5+ AutoPlugin
Scala
20
star
68

sbt-cucumber

Cucumber plugin for SBT.
Scala
20
star
69

sbt-jcstress

Trust no-one, and especially not memory visibility.
HTML
19
star
70

adept

adept helps you find, declare, and download dependencies. http://groups.google.com/group/adept-dev/
18
star
71

sbt-sriracha

Scala
17
star
72

sbt-mocha

SBT plugin for running mocha JavaScript unit tests on node
Scala
17
star
73

sbt-multi-release-jar

Support for JDK9's Multi Release JAR Files (JEP 238)
Scala
17
star
74

sbt-xjc

SBT plugin to compile an XML Schema with XJC
Scala
15
star
75

util

util modules for sbt
Scala
15
star
76

sbt-export-repo

exports your dependency graph to a preloaded local repository
Scala
15
star
77

sbt-nocomma

sbt-nocomma reduces commas from your build.sbt.
Scala
13
star
78

serialization

serialization facility for sbt
Scala
13
star
79

sbt-maven-resolver

An sbt plugin to resolve dependencies using Aether
Scala
12
star
80

sbt-core-next

sbt APIs targeted for eventual inclusion in sbt core
Scala
12
star
81

sbt-houserules

House rules for sbt modules.
Scala
12
star
82

sbt-pamflet

sbt plugin to run Pamflet (and Pamflet plugin to run sbt)
Scala
11
star
83

sbt-sdlc

Scaladoc link checker for sbt
Scala
11
star
84

sbt-appbundle

A plugin for the simple-build-tool to create an OS X application bundle.
Scala
10
star
85

bintry

your packages, delivered fresh
Scala
10
star
86

sbt-fmpp

FreeMarker Scala/Java Templating Plugin for SBT
Scala
9
star
87

sbt-ynolub

Scala
9
star
88

sbt-testng

Implementation of the sbt testing interface for TestNG, bundled with an sbt plug-in for convenience.
Scala
9
star
89

sbt-concat

sbt-web plugin for concatenating web assets
Scala
8
star
90

sbt-ant

SBT plug-in to call Ant targets from within SBT builds
Scala
7
star
91

sbtn-dist

Shell
6
star
92

sbt-community-plugins

All community plugins that opt into an uber-build
Scala
6
star
93

sbt-vimquit

an sbt plugin that adds :q command.
Scala
5
star
94

helloworld-one

An example build for sbt 1.0.0.
Scala
5
star
95

sbt-giter8-resolver

Scala
5
star
96

sbt-sequential

adds sequential tasks to sbt
Scala
4
star
97

sbt-scalashim

generates sys.error.
Scala
4
star
98

sbt-experimental

Experimental APIs to fix rough edges in sbt
Scala
3
star
99

sbt-web-build-base

Scala
3
star
100

sbt-validator

Builds sbt 1.0.x against recent versions of the sbt modules
Shell
3
star