Make SBT less surprising

sbt-surprising.md

Inspired by the effort towards better documentation, I'd like to raise a few points about SBT, that I wish could be addressed. I, myself, am not against the DSL per se, but I'd like things to be more explicit. Here's a few examples:

• an empty or missing build.sbt is a valid project (unless you use sbt-extras)
• "bare" keys are not scoped per-build, but per-project, although there is no explicit project definition
• when an explicit root project is missing, sub-projects are auto-aggregated. As you introduce a root project, you'll lose auto-aggregation
• the project macro fills in the name of the project by "reading" it from the val identifier in lazy val foo = project. This is surprising because it does not behave like regular code. I'd even argue that just using Project might be clearer

other personal observations:

• scoping is still unclear (to me), because I'd expect subprojects to inherit keys from parents, while we are expected to use inThisBuild or commonSettings
• I don't see clearly the distinction between Global and ThisBuild, which I would expect to behave the same (within the same build.sbt file)