{"id":13566536,"url":"https://github.com/sbt/sbt-release","last_synced_at":"2025-05-14T20:09:10.476Z","repository":{"id":899977,"uuid":"2583046","full_name":"sbt/sbt-release","owner":"sbt","description":"A release plugin for sbt","archived":false,"fork":false,"pushed_at":"2025-03-17T23:03:44.000Z","size":455,"stargazers_count":653,"open_issues_count":90,"forks_count":161,"subscribers_count":24,"default_branch":"master","last_synced_at":"2025-04-13T21:33:54.303Z","etag":null,"topics":["git","mercurial","sbt","sbt-plugin","scala"],"latest_commit_sha":null,"homepage":"","language":"Scala","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sbt.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2011-10-15T19:00:45.000Z","updated_at":"2025-04-05T07:22:05.000Z","dependencies_parsed_at":"2023-12-28T01:01:25.051Z","dependency_job_id":"25cbfdb3-b064-47e8-b687-e5a652b7a0b1","html_url":"https://github.com/sbt/sbt-release","commit_stats":{"total_commits":446,"total_committers":64,"mean_commits":6.96875,"dds":0.6076233183856502,"last_synced_commit":"75e89debbd5b3c168fada7cf6fe89dad2ee7e6eb"},"previous_names":[],"tags_count":34,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sbt%2Fsbt-release","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sbt%2Fsbt-release/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sbt%2Fsbt-release/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sbt%2Fsbt-release/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sbt","download_url":"https://codeload.github.com/sbt/sbt-release/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254219374,"owners_count":22034397,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["git","mercurial","sbt","sbt-plugin","scala"],"created_at":"2024-08-01T13:02:11.570Z","updated_at":"2025-05-14T20:09:10.457Z","avatar_url":"https://github.com/sbt.png","language":"Scala","readme":"# sbt-release\nThis sbt plugin provides a customizable release process that you can add to your project.\n\n[![sbt-release Scala version support](https://index.scala-lang.org/sbt/sbt-release/sbt-release/latest-by-scala-version.svg?targetType=Sbt)](https://index.scala-lang.org/sbt/sbt-release/sbt-release)\n\n**Notice:** This README contains information for the latest release. Please refer to the documents for a specific version by looking up the respective [tag](https://github.com/sbt/sbt-release/tags).\n\n## Requirements\n * sbt 1.x\n * The version of the project should follow the semantic versioning scheme on [semver.org](https://www.semver.org) with the following additions:\n   * The minor and bugfix (and beyond) part of the version are optional.\n   * There is no limit to the number of subversions you may have.\n   * The appendix after the bugfix part must be alphanumeric (`[0-9a-zA-Z]`) but may also contain dash characters `-`.\n   * These are all valid version numbers:\n     * 1.2.3\n     * 1.2.3-SNAPSHOT\n     * 1.2beta1\n     * 1.2-beta.1\n     * 1.2\n     * 1\n     * 1-BETA17\n     * 1.2.3.4.5\n     * 1.2.3.4.5-SNAPSHOT\n * A [publish repository](https://www.scala-sbt.org/1.x/docs/Publishing.html) configured. (Required only for the default release process. See further below for release process customizations.)\n * git [optional]\n\n## Usage\n\nAdd the following lines to `./project/plugins.sbt`. See the section [Using Plugins](https://www.scala-sbt.org/1.x/docs/Using-Plugins.html) in the sbt website for more information.\n\n```scala\naddSbtPlugin(\"com.github.sbt\" % \"sbt-release\" % \"1.4.0\")\n```\n\n## version.sbt\n\nSince 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.\n\nFor 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`.\n\nBy 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`.\n\n\n## Release Process\n\nThe default release process consists of the following tasks:\n\n 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.\n 1. If there are any snapshot dependencies, ask the user whether to continue or not (default: no).\n 1. Ask the user for the `release version` and the `next development version`. Sensible defaults are provided.\n 1. Run `clean`.\n 1. Run `test:test`, if any test fails, the release process is aborted.\n 1. Write `ThisBuild / version := \"$releaseVersion\"` to the file `version.sbt` and also apply this setting to the current [build state](https://www.scala-sbt.org/1.x/docs/Core-Principles.html#Introduction+to+build+state).\n 1. Commit the changes in `version.sbt`.\n 1. Tag the previous commit with `v$version` (eg. `v1.2`, `v1.2.3`).\n 1. Run `publish`.\n 1. Write `ThisBuild / version := \"nextVersion\"` to the file `version.sbt` and also apply this setting to the current build state.\n 1. Commit the changes in `version.sbt`.\n\nIn case of a failure of a task, the release process is aborted.\n\n### Non-interactive release\n\nYou can run a non-interactive release by providing the argument `with-defaults` (tab completion works) to the `release` command.\n\nFor all interactions, the following default value will be chosen:\n\n * Continue with snapshots dependencies: no\n * Release Version: current version without the qualifier (eg. `1.2-SNAPSHOT` -\u003e `1.2`)\n * Next Version: increase the minor version segment of the current version and set the qualifier to '-SNAPSHOT' (eg. `1.2.1-SNAPSHOT` -\u003e `1.3.0-SNAPSHOT`)\n * 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:\n    * ```o``` override\n    * ```k``` do not overwrite\n    * ```a``` abort (default)\n    * ```\u003ctag-name\u003e``` an explicit custom tag name (e.g. ```1.2-M3```)\n * VCS push:\n    * Abort if no remote tracking branch is set up.\n    * Abort if remote tracking branch cannot be checked (eg. via `git fetch`).\n    * Abort if the remote tracking branch has unmerged commits.\n\n### Set release version and next version as command arguments\n\nYou can set the release version using the argument `release-version` and next version with `next-version`.\n\nExample:\n\n    release release-version 1.0.99 next-version 1.2.0-SNAPSHOT\n\n### Skipping tests\n\nFor 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.\n\n### Cross building during a release\n\nSince version 0.7, *sbt-release* comes with built-in support for [cross building](https://www.scala-sbt.org/1.x/docs/Cross-Build.html) and cross publishing. A cross release can be triggered in two ways:\n\n 1. via the setting `releaseCrossBuild` (by default set to `false`)\n 1. by using the option `cross` for the `release` command\n\n    `\u003e release cross with-defaults`\n\nCombining 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`.\n\nOf the predefined release steps, the `clean`, `test`, and `publish` release steps are set up for cross building.\n\nA cross release behaves analogous to using the `+` command:\n 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`).\n 1. 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. \n\nIn the section *Customizing the release process* we take a look at how to define a `ReleaseStep` to participate in a cross build.\n\n### Versioning Strategies\n\nAs 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:\n\n * `Major`: always bumps the *major* part of the version\n * `Minor`: always bumps the *minor* part of the version\n * `Bugfix`: always bumps the *bugfix* part of the version\n * `Nano`: always bumps the *nano* part of the version\n * `Next` (**default**): bumps the last version part, including the qualifier (e.g. `0.17` -\u003e `0.18`, `0.11.7` -\u003e `0.11.8`, `3.22.3.4.91` -\u003e `3.22.3.4.92`, `1.0.0-RC1` -\u003e `1.0.0-RC2`)\n * `NextStable`: bumps exactly like `Next` except that any prerelease qualifier is excluded (e.g. `1.0.0-RC1` -\u003e `1.0.0`)\n\nUsers can set their preferred versioning strategy in `build.sbt` as follows:\n```sbt\nreleaseVersionBump := sbtrelease.Version.Bump.Major\n```\n\n### Default Versioning\n\nThe default settings make use of the helper class [`Version`](https://github.com/sbt/sbt-release/blob/master/src/main/scala/Version.scala) that ships with *sbt-release*.\n\n`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`.\n\n`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`.\n\n### Custom Versioning\n\n*sbt-release* comes with two settings for deriving the release version and the next development version from a given version.\n\nThese derived versions are used for the suggestions/defaults in the prompt and for non-interactive releases.\n\nLet's take a look at the types:\n\n```scala\nval releaseVersion     : TaskKey[String =\u003e String]\nval releaseNextVersion : TaskKey[String =\u003e String]\n```\n\nIf you want to customize the versioning, keep the following in mind:\n\n * `releaseVersion`\n   * input: the current development version\n   * output: the release version\n\n * `releaseNextVersion`\n   * input: the release version (either automatically 'chosen' in a non-interactive build or from user input)\n   * output: the next development version\n\n### Custom VCS messages\n*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:\n\n```scala\nval releaseTagComment        : TaskKey[String]\nval releaseCommitMessage     : TaskKey[String]\nval releaseNextCommitMessage : TaskKey[String]\n\n// defaults\nreleaseTagComment        := s\"Releasing ${(ThisBuild / version).value}\",\nreleaseCommitMessage     := s\"Setting version to ${(ThisBuild / version).value}\",\nreleaseNextCommitMessage := s\"Setting version to ${(ThisBuild / version).value}\",\n```\n\n### Publishing signed releases\n\nSBT is able to publish signed releases using the [sbt-pgp plugin](https://github.com/sbt/sbt-pgp).\n\nAfter setting that up for your project, you can then tell *sbt-release* to use it by setting the `releasePublishArtifactsAction` key:\n\n```scala\nreleasePublishArtifactsAction := PgpKeys.publishSigned.value\n````\n\n## Customizing the release process\n\n### Not all releases are created equal\n\nThe release process can be customized to the project's needs.\n\n  * Not using Git? Then rip it out.\n  * Want to check for the existence of release notes at the start of the release and then publish it with [posterous-sbt](https://github.com/n8han/posterous-sbt) at the end? Just add the release step.\n\n\nThe release process is defined by [State](https://www.scala-sbt.org/1.x/docs/Build-State.html) transformation functions (`State =\u003e State`), for which *sbt-release* defines this case class:\n\n```scala\ncase class ReleaseStep (\n  action: State =\u003e State,\n  check: State =\u003e State = identity,\n  enableCrossBuild: Boolean = false\n)\n```\n\nThe 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`.\n\nThe sequence of `ReleaseStep`s that make up the release process is stored in the setting `releaseProcess: SettingKey[Seq[ReleaseStep]]`.\n\nThe 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](https://www.scala-sbt.org/1.x/docs/Commands.html) in the sbt website.\n\n### Release Steps\n\nThere are basically 2 ways to creating a new `ReleaseStep`:\n\n#### Defining your own release steps\n\nYou can define your own state tansformation functions, just like *sbt-release* does, for example:\n\n```scala\nval checkOrganization = ReleaseStep(action = st =\u003e {\n  // extract the build state\n  val extracted = Project.extract(st)\n  // retrieve the value of the organization SettingKey\n  val org = extracted.get(Keys.organization)\n\n  if (org.startsWith(\"com.acme\"))\n    sys.error(\"Hey, no need to release a toy project!\")\n\n  st\n})\n```\n\nWe will later see how to let this release step participate in the release process.\n\n#### Reusing already defined tasks\n\nSometimes 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.\n\n*sbt-release* comes with a few convenience functions for converting tasks and commands to release steps:\n\n* `releaseStepTask` - Run an individual task. Does not aggregate builds.\n* `releaseStepTaskAggregated` - Run an aggregated task.\n* `releaseStepInputTask` - Run an input task, optionally taking the input to pass to it.\n* `releaseStepCommand` - Run a command.\n\nFor example:\n\n```scala\nreleaseProcess := Seq[ReleaseStep](\n  releaseStepInputTask(testOnly, \" com.example.MyTest\"),\n  releaseStepInputTask(scripted),\n  releaseStepTask(publish in subproject),\n  releaseStepCommand(\"sonatypeRelease\")\n)\n```\n\nI highly recommend to make yourself familiar with the [State API](https://www.scala-sbt.org/1.x/docs/Build-State.html) before you continue your journey to a fully customized release process.\n\n### Can we finally customize that release process, please?\n\nYes, and as a start, let's take a look at the [default definition](https://github.com/sbt/sbt-release/blob/v1.0.15/src/main/scala/ReleasePlugin.scala#L250) of `releaseProcess`:\n\n#### The default release process\n\n```scala\nimport ReleaseTransformations._\n\n// ...\n\nreleaseProcess := Seq[ReleaseStep](\n  checkSnapshotDependencies,              // : ReleaseStep\n  inquireVersions,                        // : ReleaseStep\n  runClean,                               // : ReleaseStep\n  runTest,                                // : ReleaseStep\n  setReleaseVersion,                      // : ReleaseStep\n  commitReleaseVersion,                   // : ReleaseStep, performs the initial git checks\n  tagRelease,                             // : ReleaseStep\n  publishArtifacts,                       // : ReleaseStep, checks whether `publishTo` is properly set up\n  setNextVersion,                         // : ReleaseStep\n  commitNextVersion,                      // : ReleaseStep\n  pushChanges                             // : ReleaseStep, also checks that an upstream branch is properly configured\n)\n```\n\nThe names of the individual steps of the release process are pretty much self-describing.\nNotice how we can just reuse the `publish` task by utilizing the `releaseTask` helper function,\nbut keep in mind that it needs to be properly scoped (more info on [Scopes](https://www.scala-sbt.org/1.x/docs/Scopes.html)).\n\nNote, 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\nby setting the `releaseIgnoreUntrackedFiles` key to `true`.\n\n#### No Git, and no toy projects!\n\nLet's modify the previous release process and remove the Git related steps, who uses that anyway.\n\n```scala\nimport ReleaseTransformations._\n\n// ...\n\nReleaseKeys.releaseProcess := Seq[ReleaseStep](\n  checkOrganization,                // Look Ma', my own release step!\n  checkSnapshotDependencies,\n  inquireVersions,\n  runTest,\n  setReleaseVersion,\n  publishArtifacts,\n  setNextVersion\n)\n```\n\nOverall, the process stayed pretty much the same:\n\n  * The Git related steps were left out.\n  * Our `checkOrganization` task was added in the beginning, just to be sure this is a serious project.\n\n#### Release notes anyone?\nNow let's also add steps for [posterous-sbt](https://github.com/n8han/posterous-sbt):\n\n```scala\nimport posterous.Publish._\nimport ReleaseTransformations._\n\n// ...\n\nval publishReleaseNotes = (ref: ProjectRef) =\u003e ReleaseStep(\n  check  = releaseStepTaskAggregated(check in Posterous in ref),   // upfront check\n  action = releaseStepTaskAggregated(publish in Posterous in ref) // publish release notes\n)\n\n// ...\n\nReleaseKeys.releaseProcess \u003c\u003c= thisProjectRef apply { ref =\u003e\n  import ReleaseStateTransformations._\n  Seq[ReleaseStep](\n    checkOrganization,\n    checkSnapshotDependencies,\n    inquireVersions,\n    runTest,\n    setReleaseVersion,\n    publishArtifacts,\n    publishReleaseNotes(ref) // we need to forward `thisProjectRef` for proper scoping of the underlying tasks\n    setNextVersion\n  )\n}\n```\n\nThe `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.\nAfter publishing the actual build artifacts, we also publish the release notes.\n\n## Credits\nThank you, [Jason](https://github.com/retronym) and [Mark](https://github.com/harrah), for your feedback and ideas.\n\n## Contributors\n[Johannes Rudolph](https://github.com/jrudolph), [Espen Wiborg](https://github.com/espenhw), [Eric Bowman](https://github.com/ebowman), [Petteri Valkonen](https://github.com/pvalkone),\n[Gary Coady](https://github.com/garycoady), [Alexey Alekhin](https://github.com/laughedelic), [Andrew Gustafson](https://github.com/agustafson), [Paul Davies](https://github.com/paulmdavies),\n[Stanislav Savulchik](https://github.com/savulchik), [Tim Van Laer](https://github.com/timvlaer), [Lars Hupel](https://github.com/larsrh)\n\n## License\nCopyright (c) 2011-2014 Gerolf Seitz\n\nPublished under the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0.txt)\n","funding_links":[],"categories":["BUILD \u0026 RELEASE","Scala","Table of Contents","Sbt plugins","\u003ca name=\"Scala\"\u003e\u003c/a\u003eScala"],"sub_categories":["Sbt plugins"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsbt%2Fsbt-release","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsbt%2Fsbt-release","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsbt%2Fsbt-release/lists"}