🎠 Deprecate and eventually remove bare settings

[eed3si9n]

https://twitter.com/tpolecat/status/1340380781538062341

steps

organization := "example"
scalaVersion := "2.13.4"
name := "hello"

lazy val root = (project in file("."))
lazy val core = (project in file("core"))
lazy val app = (project in file("app"))

problem

I've been trying to discourage people from using bare .sbt build definition, but people do and often it leads to confusion since they tend to assume that the scalaVersion above would carry over to the subprojects.

expectation

Now that the ecosystem has largely migrated to sbt 1.x, we can cut off the vestige of sbt 0.13 era and deprecate bare settings against implicit root subproject in the proper build.

[dwijnand]

Presumably project/plugins.sbt would continue to work as it does today.

[eed3si9n]

@dwijnand Yup.

implicit root subproject in the proper build.

That's why I specified "proper build" as opposed to metabuild

[SethTisue]

If the implicit root project is the only project, would there still be a deprecation warning?

[eed3si9n]

@SethTisue If we want to remove the idea of projectless settings altogether in sbt 2.x, I think it would make sense to warn even if it's the only subproject in the build.

[SethTisue]

If we want to remove the idea of projectless settings altogether in sbt 2.x,

That's a pretty big if :-)

Here's what I would suggest:

For now, only issue a deprecation warning if there are actually any non-root projects.

That would maximize helpfulness (calling attention to inadvertent foot-shooting) and minimize annoyingness for users who aren't aware of the overall trajectory of planned future sbt changes. Users who just want to 1) build their thing, 2) following advice and examples and books widely available across the Internet for the past decade.

If sbt 2.x goes forward with making a fundamental change in this area, then once 2.x is actually out (or at least in RCs, say), then consider going back and having 1.x warn more broadly, perhaps only under some kind of migration flag.

[SethTisue]

If we want to remove the idea of projectless settings altogether in sbt 2.x

(Is there a canonical ticket on this? I have some further thoughts about this, but I'm not sure whether to put them here, or have this ticket be more narrowly just about deprecation warnings in 1.x.)

[eed3si9n]

If we want to remove the idea of projectless settings altogether in sbt 2.x

Is there a canonical ticket on this?

This is issue is meant to express Rob's and my intent on doing so.

[SethTisue]

First, I'm totally on board with deprecating bare settings in multi-project builds, I see no downside there.

As for the broader deprecation/removal, well, you can probably guess that I like bare settings for single-project builds very very much. This won't be the first time we've gone back and forth about this :-), notably at scala/scala-seed.g8#2 and scala/scala-seed.g8#4 and scala/scala-seed.g8#9, tickets that anyone interested in this will probably want to review. I know software isn't a democracy, but there are a lot of people on those tickets arguing in favor of bare settings, with their thumbs and their words, and almost nobody taking the no-bare-settings position.

I've never been convinced by the "people are eventually going to need to have multiple projects in their builds, so we might as well teach them the multi-project style from day 1" argument. I suspect that it seems appealing because we're so used to Scala OSS builds, which typically sprout subprojects for all sorts of reasons, including for cross-building. But I strongly suspect that there is a large "silent majority" of sbt users out there with simple, single-project, JVM-only builds. We don't hear from them that, I suspect, because sbt is remarkably easy to use in that scenario. It Just Works (TM). And I think sbt should work hard to make that kind of simple, uncomplicated usage of sbt stay simple and uncomplicated. And I think bare settings do that very well.

As I wrote last year:

You can learn a lot of Scala, and get a lot of value out of sbt along the way, before ever wanting or needing to know anything about multi-project builds at all. (I used Scala and sbt myself for years without ever learning that.)

In the context of teaching Scala to newcomers, I think the move to a multi-project build is in the learner's distant future, so to prepare them for that move so early is simply a pedagogical mistake that 1) distracts the learner from more important issues at their stage of learning, and not incidentally 2) gives them an unnecessarily negative impression of sbt.

Also, a lesser concern, but: it seems rather strange to me to allow bare settings in projects/plugins.sbt but prohibit them in root build.sbt. What's the argument for introducing that inconsistency? If bare settings continued to be allowed in metabuilds, then it seems to me like you aren't enabling any simplifications either in the codebase or in one's mental model of how sbt works.

cc @tpolecat

[eed3si9n]

I'll try to explore my take on this topic, but I just want to preface that I don't want to come off as high-horse preachy. Certain things are facts, but mostly these are my subjective opinions.

In sbt meetings, one of the phrases I use a lot is "cognitive load". Often people feel the sense of disorientation / lostness looking at unfamiliar build tools and languages. Gradually the users gain footing by memorizing basic patterns, making a few variations, and confirming that the outcome matches the expectation. Years ago when I started out as an enthusiastic plugin author, sbt was notorious for its difficulty in learning, and people making heads or tails by looking at the build files.

At least in terms of the build.sbt syntax, the history of sbt post-2014 is the history of unification in the hopes of reducing the cognitive load:

• := and .value macro by Mark and Josh (1c22478)
• No blank lines between settings by Andrzej Jozwik (Natural whitespace handling for SBT configuration parser AKA 'no more blankies' #1645)
• Removal of project/Build.scala style ([sbt 1.0] sbt.Build => sbt.internal.BuildDef #2524) by me
• Slash syntax to unify shell syntax and build.sbt (Unify sbt shell and build.sbt syntax (scope path syntax) #3434) by me

At each juncture, there were certain tradeoff that we had to make either in terms of migration cost, code complexity, performance, or usability of some use cases. For example, <project>/<config>:<intask>::task might perform better for tab-completion if the users could ever remember how to interpret the shell syntax.

Among the above changes, the most highly contested probably was the deprecation and eventual removal of project/Build.scala. It's totally understandable because being actual *.scala gave users the footing to feel less-lost about what is going on in the build. I have zero regrets on removing this in sbt 1.x:

• build.sbt DSL requires its own understanding regardless of the file extension, so the warm feeling that comes from project/Build.scala is mostly false sense of security.
• All plugins in sbt 1.x are AutoPlugin that automatically generate import clause in build.sbt. Using project/Build.scala requires hand-rolling the import clause.

But ultimately the biggest reason is having 3 ways to express the same thing (subproject) adds needless cognitive load to the new and experienced users alike. The 3 ways were:

1. Multi-project build.sbt
2. Bare-style build.sbt
3. Build.scala build definition

We are down to 2.

I've never been convinced by the "people are eventually going to need to have multiple projects in their builds, so we might as well teach them the multi-project style from day 1" argument.

So my reasoning is not because the new users will eventually need multiple projects. Instead my reasoning is: as a maintainer, I want to reduce the freedom of how the builds are written so I (or future maintainers) won't have to answer questions about them, and because bare style cannot replace multi-project style today, but multi-project style can subsume the bare style.

[dwijnand]

The build.sbt, core/build.sbt, & app/build.sbt style is still possible and not deprecated (recently encountered in a support case). Perhaps that still comes under your bare-style build.sbt way. (That includes, btw, the project/foo.sbt, project/bar.sbt, etc, setup, which I was never a fan of.) I'm more in favour of deprecating and removing that, while I'm more on the fence on root project bare settings (I see the value of both arguments...). I should've written down what I'd discovered while trying to study #2899 as I don't remember any more...

[eed3si9n]

The build.sbt, core/build.sbt, & app/build.sbt style is still possible and not deprecated (recently encountered in a support case). Perhaps that still comes under your bare-style build.sbt way. (That includes, btw, the project/foo.sbt, project/bar.sbt, etc, setup, which I was never a fan of.)

Yea. That makes sense.

Part of me want to hold on to the idea of decentralized *.sbt files because being able to define build definitions in a nested directory structure is actually a useful feature, especially if the sub-graph can act as an independent build. Maven does this the best using parent POMs, and Bazel works somewhat like that with BUILD file created per target (although subdirectories cannot function as a standalone build).

If we want to evolve sbt into supporting this kind of build of multiple builds usage, using source dependencies like sbt-sriracha would probably be the way to go, so overall I'm in agreement with the deprecation of decentralized bare-style *.sbt.