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

https://github.com/sbt/website/pull/306#discussion_r94264182 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.

Read the linked discussion and inspect the Getting Started guide's first and later examples for their use of inThisBuild(...). Compare the documented examples for consistency and verify that the final guide clearly explains or consistently avoids the build-level setting; the issue's seven-comment thread contains the relevant tradeoffs.