Unidoc may fail if dependencies of submodules don't agree

[jrudolph]

See akka/akka#29067

That's because unidoc just concatenates the classpaths from all the aggregated submodules. That might mean that two versions of the same artifact end up on the classpath and it depends on ordering which one is chosen. It doesn't do conflict resolution like update does.

In the best case, it would instead try to build an aggregate module and run a full update on that (might be hard to achieve).

[alexklibisz]

I've found this mainly happens when there are two transitive dependencies on binary-incompatible versions of the same artifact. e.g. your project depends on A and B. A depends on C version 1.0, B depends on C version 2.0. That usually points to a more serious problem, as you probably shouldn't release code that depends on binary-incompatible transitives. It's still not ideal that sbt-unidoc uses this primitive approach of concatenating the classpaths, but IMO it's actually kind of good that it breaks before you release your project.

[armanbilge]

I just ran into this as well. As far as I understand:

1. It is not related to binary-compatibility at all, it is a source-compatibility issue.
2. Even if the different versions are backwards-compatible, you can get this error.

That is to say, it can show up in 100% normal use, without any serious underlying issue.

In my situation, I encountered it because one of my modules is depending on Cats Effect 3.4.0 and using some new APIs introduced in that version. Other modules are depending on http4s (and not directly on Cats Effect), which was transitively bringing in Cats Effect 3.3.14. In the unidocs, the transitive Cats Effect 3.3.14 was winning out over 3.4.0 directly depended on by the other module.

I actually don't think it's too hard to fix.

sbt-unidoc/src/main/scala/sbtunidoc/BaseUnidocPlugin.scala

Line 30 in eb2f8e0

unidoc / fullClasspath := (unidoc / unidocAllClasspaths).value.flatten.distinct.sortBy { _.data.getName },

I think that should do a groupBy based on org and module id, and then take the latest version from each group. Does sbt have an easy API for sorting versions?