Should we recommend the use of `inThisBuild(...)` in the Getting Started guide?

[eed3si9n]

#306 (comment) Li Haoyi wrote:

If we are going to teach people inThisBuild in the first example, we should continue with that in all further examples. If we think it's too complicated to explain, we should strip it out of the first example.

So far it seems to me able half-half with and without inThisBuild; my personal vote would be to strip it out, since I've written tons of SBT configs and haven't ever used it, but I don't mind as long as it's consistent throughout

Recap on inThisBuild(...):

• Was introduced in sbt 0.13.9, so it's a relatively new feature.
• inThisBuild(...) puts the setting in the build scope, which applies to all subprojects in the build.
• Because the value is centralized to a setting, it makes it easier to programmatically change it. This is useful for version (e.g. sbt-release uses version in ThisBuild)
• A newly created subproject will be correct by default without manually adding in the common settings.

Downsides:

• It requires the user to understand subtle scoping rules around project-scoping vs build level settings.
• Build level settings are useful for simple pure values, but they won't work for settings and tasks dependent on project-scoped keys such as baseDirectory. In that sense it's more difficult to understand compared to commonSettings.

[dwijnand]

I say yes.

[eed3si9n]

I'm leaning towards avoiding inThisBuild(...) in the first pages, explaining it in the Scopes page, and bringing it up in Multi-Project. As useful as it is, it has too much quirks.

[SethTisue]

I'm leaning towards avoiding inThisBuild(...) in the first pages

agree

[fommil]

definitely recommend using it. If you think it's too complex a topic, then perhaps it should be the default scope for "top level" settings in build.sbt files (I think it should be!)

[evacchi]

@fommil I think most people here would agree, but it might be too much of a breaking change for existing builds (besides, as of today I'm having a hard time understanding the meaning of ThisBuild v. Global; but that's another story)

[jastice]

@fommil I agree.

Something to consider for 1.0? The inThisBuild syntax makes basic examples look more complex than necessary.

[dwijnand]

It's a breaking change in the build, which we're avoiding in the 0.13 -> 1.0 migration.

(Btw, turns out that option was considered back in the day, and I too wish it had been picked - https://twitter.com/dwijnand/status/826051471485652992)