Yes, this is a problem, and a big one. IMO, docs are great but they are not teaching sbt, but showing how to do stuff with it (which is conceptually different). It seems that there's not a reasonable getting started tutorial. I think this was the idea with https://www.manning.com/books/sbt-in-action, but it's a paid book which is less than ideal for the OSS community around sbt.
This will come with sbt 1.0 soon. We will help you get there by easing the migration between 0.13 and 1.0 with sbt-migration-rewrites.
Oh, this is a good one. It's true that plugin documentation is poor and could be improved, both for writing plugins and finding them. I feel we sometimes reinvent the wheel many times when there's a plugin that solves our problem, but we haven't found it.
Regarding Scaladex, @MasseGuillaume and @julienrf have recently worked on that use case. For now, Scaladex can show sbt plugins published to Maven Central, but cannot support sbt plugins in the sbt Bintray repository because there is no way to link them to GitHub if users don't fill in the vcs information on the repository (
scmInfo does not exist in ivy style artifacts). Users that wish to show their plugins have to manually claim them.
Yes, I feel this too. It would be interesting to create a FAQ with a gist of the solution and links to the original answers. There are valuable answers in Stack Overflow.
I proposed several times to format the sources, and it eventually crystallised in this pull request that was closed by lack of agreement. I hope we can resurrect it some time soon and agree on a solution.
Macro implementations are pretty well documented, so I guess you're referring to the use of macros. My problem with them is that their contract is not publicly known to users, and the documentation does not do a good job to thoroughly describe their use. Also, macro constructs can often be used for different use cases that are conceptually different, which is confusing.
I echo your suggestion to keep the Scala API alive for users that don't want to write in a macro style. There are several disadvantages by not using the sbt DSL (for example, you lose task deduplication). But, in my opinion, this is not a problem if users value more Scala semantics over sbt properties and they don't want to spend time learning another API.
In my opinion, the regular macros-free API should be documented in the website (it's not documented right now). I feel that the direction that sbt 1.0 is taking goes aggressively towards a DSL style and while I think this is a reasonable approach for them, I believe that the two styles should be supported by sbt, because not all users share their vision.
To me, writing non-macro code has three big advantages:
- You don't need to learn the sbt semantics and DSL API (which is big). Regular Scala code suffices.
- You have total control over task execution.
- Compilation is faster -- sbt macro expansion is expensive.
However, @tpolecat, in order to make that move you need to get in touch with @eed3si9n and @dwijnand. I have already expressed these opinions to them, so I cannot do anything else than voicing them again in public. I suggest that you open a ticket in the sbt issue tracker to discuss it.