Repository navigation
Essential: Installation
-
Motivation: First time here? Understand what
sbt-release-earlydoes and how. - Requirements: Wanna install? Make sure your system is set up.
- Installation: You know everything and just want to install it? Come here.
- Use: Check instructions on how to use the plugin.
- Configuration: click on the link, you're on the wrong page.
Every time you push a commit to a branch, sbt-release-early will release an
artifact with a version derived from the git metadata (version and distance from
last git tag). For example, 0.3.0+10-4f489199, where 10 is the distance
and the suffix is the commit hash.
Every time you push a tag to a repository, sbt-release-early will release an
artifact with that tag version. This feature is usually used to cut final releases,
for example, v0.1.0.
sbt-release-early takes a distinct approach to releases.
While some projects decide to declare versions in sbt files, sbt-release-early
derives the versions of your project from your git tags. This has several benefits:
- Reproducibility.
- Tag uniqueness. Git prevents you from trying to release a version twice by mistake.
- No need to push commits to bump up the versions of your projects.
- The tag history shows all the released versions over the time of a project.
- You can avoid releasing artifacts that can be resolved from
resolvers.
These properties reduce the complexity of handling releases significantly. The repository revision history becomes the ultimate truth and build-related tasks are easy to set up -- no need to resolve the latest version or scrape the library version from its sbt build.
Note that the tag uniqueness property only holds if you don't delete an already pushed tag. This is so bad practice that we assume people are sensible and don't do it.
The version lingo is extracted from the Semantic Versioning document.
This documentation and this plugin assumes that:
- Version numbers are final if they only consist of a MAJOR, MINOR and PATCH VERSION.
For example,
1.0.1,2.4.98and10.1.6are final releases. - Any other version number that contains build metadata or qualifiers like
RC,betaoralphaare considered SNAPSHOTs even if they lack the-SNAPSHOTsuffix. For example,0.3.0+10-4f489199,8.9.1-1f43aa21or1.0.0-RCare snapshots.
Note that the snapshot does not have a precise and commonly accepted definition.
sbt-release-earlys definition differs from the common understanding of snapshot
versions in the Scala community.
sbt-release-early considers the most literal definition of snapshot: it's a release
that mirrors the codebase at a given point of time and whose artifacts could not provide
the same guarantees as final releases. These guarantees are established by library authors.
Snapshots have important shortcomings:
- They are not reproducible: downstream users can get different snapshot releases depending on the time they resolve/update them.
- Their resolution times are slower: build tools have to check all artifacts in all resolvers to choose the appropriate version.
The use of snapshots is no longer justified with sbt-release-early and sbt plugins like
sbt-dynver that derive automatic
versions from git invariants. sbt-release-early keeps your builds faster
and more reproducible.
The use of snapshots may be justified for local development, but should be prohibited at
the moment it leaves the local workspace. sbt-release-early enables this use case.
I already use the popular
sbt-releaseplugin to create my own release pipeline. Why should I usesbt-release-earlyinstead? Why have you spent time in this release plugin?
In my view, sbt-release makes ad-hoc design decisions that:
- Complicate its use and understanding;
- Require longer time to master; and,
- Hamper maintenance and addition of new features.
We've created sbt-release-early to become the de-facto releasing plugin in the sbt community. For
that, we've focused on simplicity and extensibility. That's why we've redesigned the releasing sbt experience.
-
sbt-release-earlycan be invoked only for concrete projects and aggregation works out of the box.sbt-releasehas clunky support for aggregation and uses commands, which are global and cannot be executed only for a project. -
sbt-release-earlyis easier to learn and customize. It reuses the task graph and does not require an ad-hoc dsl to specify the release pipeline. This alone eases the learning curve considerably.- Do you want to run a task after
publish? UsedependsOn. - Do you want to run a task before
publish? UsetriggeredBy. - Do you want to change one pipeline step? No need to copy-paste all the
sbt-releasedefault steps.
- Do you want to run a task after
-
sbt-release-earlyis only about releasing.sbt-releasetries to create a release pipeline that aggregates lots of complicated steps (running tests, reading git tags, et cetera). Some drawbacks that come to mind:- You cannot reuse your release pipeline without waiting for all these steps to finish.
- Running tests is insecure in CI servers.
-
sbt-release-earlyencourages remote releases in CI servers, whilesbt-release's design is biased towards local releases (requiring users' input on several release steps). -
sbt-release-earlyabstracts over whichever publisher you want to release to.sbt-releaseforces you to change the underlying publish sbt plugins by hand every time. -
sbt-release-earlyhas an opinionated handling of versions (delegating insbt-dynver),sbt-releaserelies heavily on-SNAPSHOTs and forces users to set the versions in an sbt file. -
sbt-release-earlycan be called directly from other plugins.sbt-releasecannot do it without using internal tricks to invoke commands. These tricks slow down sbt. -
sbt-release-earlyis actively maintained by the Scala Center and excellent external contributors.sbt-releaseis rarely updated. -
sbt-release-earlywill not publish a project if an artifact of that project for the given version can be resolved, because it assumes that it has already been released.sbt-releasewill try to release and override the previous artifacts.
-
sbt-release-earlycannot suggest a version. The version is always set from the VCS environment.
To use sbt-release-early, you must:
- Use git and have it executable both locally and in the CI (required by sbt-dynver).
- Have a GPG key and publish it to a PGP server like pgp.mit.edu.
Don't you meet these requirements?
- Install git and make it executable (for all the platforms).
- Read the guide to create and publish your own gpg key.
This plugin depends on the following sbt plugins:
-
sbt-dynver, version2.0.0. -
sbt-pgp, version1.0.1. -
sbt-bintray, version0.5.1. -
sbt-sonatype, version1.1.
If you already depend on them, remove them from your plugins.sbt file. The
addSbtPlugin line above will bring them in automatically.
Add the plugin to your build with:
// defined in project/plugins.sbt
addSbtPlugin("ch.epfl.scala" % "sbt-release-early" % "2.1.1")To find out what's the last available stable release, check the tag releases in this repository.
These are the last published versions to Maven Central.
Note that on-merge releases have no binary or source compatibility guarantees. They include changes that have been merged from pull requests and had not yet been as scrutinized as possible.
- Make sure you fulfill all the requirements.
- Make sure you understand what the plugin does and how.
- Make sure your sbt build is set up correctly (by reading the Configuration).
- Make sure your CI server is ready (by reading the How To's on the sidebar).
- Run
sbt releaseEarlyin your CI and have fun.
This is a Scala Center project, originally created by jvican. It now powers the Scala Platform sbt plugin and several Scala Center projects. If you find it useful, give the Center a shout-out in our official Twitter account or let us know in our Gitter channel. Your feedback is important and motivates us to keep improving this plugin.