Repository files navigation

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

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

• sbt 1.x
• The version of the project should follow the semantic versioning scheme onsemver.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
• Apublish repository configured. (Required only for the default release process. See further below for release process customizations.)
• git [optional]

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

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

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 settingreleaseVersionFile, which is set tofile("version.sbt") by default and points to$PROJECT_ROOT/version.sbt.

By default the version is set on the build level (usingThisBuild / version). This behavior can be controlled by settingreleaseUseGlobalVersion tofalse, after which a version likeversion := "1.2.3" will be written toversion.sbt.

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 therelease version and thenext development version. Sensible defaults are provided.
4. Runclean.
5. Runtest, if any test fails, the release process is aborted.
6. WriteThisBuild / version := "$releaseVersion" to the fileversion.sbt and also apply this setting to the currentbuild state.
7. Commit the changes inversion.sbt.
8. Tag the previous commit withv$version (eg.v1.2,v1.2.3).
9. Runpublish.
10. WriteThisBuild / version := "nextVersion" to the fileversion.sbt and also apply this setting to the current build state.
11. Commit the changes inversion.sbt.

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

You can run a non-interactive release by providing the argumentwith-defaults (tab completion works) to therelease 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 bydefault-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. viagit fetch).
  • Abort if the remote tracking branch has unmerged commits.

You can set the release version using the argumentrelease-version and next version withnext-version.

Example:

release release-version 1.0.99 next-version 1.2.0-SNAPSHOT

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

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

1. via the settingreleaseCrossBuild (by default set tofalse)

2. by using the optioncross for therelease 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 usingreleaseCrossBuild := false and runningrelease cross.

Of the predefined release steps, theclean,test, andpublish release steps are set up for cross building.

A cross release behaves analogous to using the+ command:

1. If nocrossScalaVersions are set, then runningrelease orrelease cross will not trigger a cross release (i.e. run the release with the scala version specified in the settingscalaVersion).
2. If thecrossScalaVersions setting is set, then only these scala versions will be used. Make sure to include the regular/defaultscalaVersion in thecrossScalaVersions setting as well. Note that setting runningrelease cross on a root project withcrossScalaVersions set toNil will not release anything.

In the sectionCustomizing the release process we take a look at how to define aReleaseStep to participate in a cross build.

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

• Major: always bumps themajor part of the version
• Minor: always bumps theminor part of the version
• Bugfix: always bumps thebugfix part of the version
• Nano: always bumps thenano 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 likeNext except that any prerelease qualifier is excluded (e.g.1.0.0-RC1 ->1.0.0)

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

releaseVersionBump:= sbtrelease.Version.Bump.Major

The default settings make use of the helper classVersion that ships withsbt-release.

releaseVersion: The current version in version.sbt, without the "-SNAPSHOT" ending. So, ifversion.sbt contains1.0.0-SNAPSHOT, the release version will be set to1.0.0.

releaseNextVersion: The "bumped" version according to the versioning strategy (explained above), including the-SNAPSHOT ending. So, ifreleaseVersion is1.0.0,releaseNextVersion will be1.0.1-SNAPSHOT.

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:

valreleaseVersion:TaskKey[String=>String]valreleaseNextVersion: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

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:

valreleaseTagComment:TaskKey[String]valreleaseCommitMessage:TaskKey[String]valreleaseNextCommitMessage:TaskKey[String]// defaultsreleaseTagComment:=s"Releasing${(ThisBuild/ version).value}",releaseCommitMessage:=s"Setting version to${(ThisBuild/ version).value}",releaseNextCommitMessage:=s"Setting version to${(ThisBuild/ version).value}",

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

After setting that up for your project, you can then tellsbt-release to use it by setting thereleasePublishArtifactsAction key:

releasePublishArtifactsAction:=PgpKeys.publishSigned.value

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 withposterous-sbt at the end? Just add the release step.

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

caseclassReleaseStep (action:State=>State,check:State=>State= identity,enableCrossBuild:Boolean=false)

The functionaction is used to perform the actual release step. Additionally, each release step can provide acheck 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 propertyenableCrossBuild tellssbt-release whether or not a particularReleaseStep needs to be executed for the specifiedcrossScalaVersions.

The sequence ofReleaseSteps that make up the release process is stored in the settingreleaseProcess: SettingKey[Seq[ReleaseStep]].

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

There are basically 2 ways to creating a newReleaseStep:

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

valcheckOrganization=ReleaseStep(action= st=> {// extract the build statevalextracted=Project.extract(st)// retrieve the value of the organization SettingKeyvalorg= 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.

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(subproject/ publishSigned),  releaseStepCommand("sonaRelease"))

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

Yes, and as a start, let's take a look at thedefault definition ofreleaseProcess:

importReleaseTransformations._// ...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 thepublish task by utilizing thereleaseTask helper function,but keep in mind that it needs to be properly scoped (more info onScopes).

Note, thecommitReleaseVersion step requires that the working directory has no untracked files by default. It will abort the release in this case. You may disable this checkby setting thereleaseIgnoreUntrackedFiles key totrue.

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

importReleaseTransformations._// ...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.
• OurcheckOrganization task was added in the beginning, just to be sure this is a serious project.

Now let's also add steps forposterous-sbt:

importposterous.Publish._importReleaseTransformations._// ...valpublishReleaseNotes= (ref:ProjectRef)=>ReleaseStep(  check= releaseStepTaskAggregated(check inPosterous in ref),// upfront check  action= releaseStepTaskAggregated(publish inPosterous in ref)// publish release notes)// ...ReleaseKeys.releaseProcess<<= thisProjectRef apply { ref=>importReleaseStateTransformations._Seq[ReleaseStep](    checkOrganization,    checkSnapshotDependencies,    inquireVersions,    runTest,    setReleaseVersion,    publishArtifacts,    publishReleaseNotes(ref)// we need to forward `thisProjectRef` for proper scoping of the underlying tasks    setNextVersion  )}

Thecheck 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.

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

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

Copyright (c) 2011-2014 Gerolf Seitz

Published under theApache License 2.0