Developer’s Guide (Work in progress)

This is the set of documentation about the future architecture of sbt.
The target audience of this document is the sbt plugin authors
and sbt developers. See also How can I help?

Towards sbt 1.0

On 2008-12-18, Mark Harrah announced sbt 0.3.2 as the initial release of sbt.
Mark remained the primary author of sbt until sbt 0.13.1 (2013-12-11).
In 2014, sbt project was handed over to the authors of this document Josh Suereth
and Eugene Yokota.

As we move towards sbt 1.0, we wish to stabilize what’s already stable
and innovate where it matters. There are several levels of stability:

conceptual stability

source compatibility of the build definition

binary compatibility of the plugins

Concepts

Conceptually, sbt has been stable on what it does:

incremental compilation that supports Scala

dependency management that’s aware of Scala’s binary compatibility

task and plugins system that’s extensible using Scala

a text-based interactive shell

The only thing that we plan to change is the last point.
In sbt 1.0, we will replace the interactive shell with sbt server
that’s accessible via JSON API and a text-based client.

Source compatibility of the build definition

Source compatibility means that a build source that worked for sbt version A
works for another version B without modification.
Our goal for sbt 1.0 is to adopt Semantic Versioning, and maintain
source compatibility of the build during 1.x.y.

Binary compatibility of the plugins

Binary compatibility (“bincompat”) of the plugins means that a plugin
that was published for sbt version A works for another version B without recompilation.
sbt 0.13 has kept binary compatibility for 18 months as of March 2015.
The stability here helps maintain the sbt plugin ecosystem.
Our goal for sbt 1.0 is to adopt Semantic Versioning, and maintain
binary compatibility of the build during 1.x.y.

From the development perspective, maintaining binary compatibility becomes
an additional constraint that we need to worry about whenever we make changes.
The root of the problem is that sbt 0.13 does not distinguish between public API
and internal implementation. Most things are open to plugins.