Dokka <2.0.0-Beta> has been released! The star of ...

# dokka

[Oleg Yukhnevich]

Dokka 2.0.0-Beta has been released!
The star of the release is the preview of Dokka's Gradle plugin v2 based on Dokkatoo!
Please check the migration guide for the update procedure, we would really appreciate your feedback! kodee loving

DGP v2 introduces significant improvements to DGP, aligning more closely with Gradle best practices:
• Fully supports Gradle configuration cache and build cache, which improves performance and simplifies build work.
• Uses an intuitive top-level DSL configuration instead of a low-level task-based setup, which simplifies the build scripts and their readability.
• Takes a more declarative approach to documentation aggregation, which makes multi-project documentation easier to manage.
• Adopts Gradle types, which leads to better performance.
• Uses a type-safe plugin configuration, which improves the reliability and maintainability of your build scripts.

[mbonnin]

This got me confused a little bit:

org.jetbrains.dokka.experimental.gradle.pluginMode=V2EnabledWithHelpers

I thought it was only for the helper but that the default would still be V2, which is not the case and I had to do

org.jetbrains.dokka.experimental.gradle.pluginMode=V2Enabled

[mbonnin]

More generally, not a fan of gradle.properties because:
• They have no API lifecycle (experimental/deprecation or even kdoc) so my gradle.properties end up being a cemetery of once experimental flags
• They play really bad with included builds. What gradle.properties is used? I never know 🤷

[Oleg Yukhnevich]

I thought it was only for the helper but that the default would still be V2

The reason is we don't want to break current users build-scripts just when they upgraded to 2.0.0, because V2 is really like the all new plugin and explicit migration is needed. Still V2 will become default in future

More generally, not a fan of gradle.properties because:

I mostly agree, but the alternative here would be:
• break everything and just replace plugin
• separate plugin ID (e.g org.jetbrains.dokka2)
And we decided, that the variant with gradle.properties will be better for both compatibility and future, when we are going to make DGP v2 the default

Regarding API lifecycle - I think that it could be rather easily handled on plugin side, e.g we could warn (or even fail the build) when there are unnecessary properties related to DGP

[mbonnin]

we don't want to break current users build-scripts just when they upgraded to 2.0.0

If I update to 2.0.0, I'm ok with breaking changes.

separate plugin ID (e.g org.jetbrains.dokka2)

Why not org.jetbrains.dokka.v1 ? (which actually is not that far from not updating)

we could warn (or even fail the build) when there are unnecessary properties related to DGP

You'll have to keep code for old Gradle properties in the dokka plugin forever because you don't know how long it'll take everyone to update their gradle.properties. And even then, there's no typesafety nor IDE support for gradle.properties (nor included build support)

[tapchicoma]

Regarding old entries in gradle.properties - inside KGP not so long ago we've introduced special warning if gradle.properties contains some properties that was removed. It should help in some way and maybe Dokka could use the same approach here

[Oleg Yukhnevich]

If I update to 2.0.0, I'm ok with breaking changes.

the main problem with such breaking changes in build-scripts (e.g in Gradle plugins) is that if you've just updated version and there are some breaking changes, you will not be able to do sync (in IDE) the changes if some changes are incompatible - and so a lot of thing will be unresolved
the case with library breaking changes is much easier, as you will at least be able to access all APIs right away

Why not org.jetbrains.dokka.v1

not sure I understand how v1 could solve the problem, that we want in the end to have org.jetbrains.dokka as the ID for future new DGP
We could move old DGP to v1, but it will again cause breaking changes when just updating version

So we decided to go safer and introduce deprecation of old DGP more gradually - even if it's Dokka 2.0.0 (updated MAJOR version not always means breaking changes - hello K2) kodee floating

[mbonnin]

> if you've just updated version and there are some breaking changes, you will not be able to do sync (in IDE) the changes if some changes are incompatible
Yea that's such a huge pain. I wish Gradle handled classpath differently (i.e. define the classpath outside the build script) but it's probably not for anytime soon.
> We could move old DGP to v1, but it will again cause breaking changes when just updating version
I think I'd prefer that. If I "just" bump the version, I get the new long term behaviour and if I'm concerned about migration helpers I can opt-in the migration helpers (by changing the plugin id here). Agree it's in the realm of personal preference here.

[mbonnin]

the case with library breaking changes is much easier, as you will at least be able to access all APIs right away

This is why I moved almost all my build logic to a build-logic included build 😄 . This way all the Gradle plugins are libraries again 🎉

[mbonnin]

Hopefully declarative Gradle can help with all of that 🤞

[Zac Sweers]

I found it confusing that this release is actually 2.0.0-Beta but the linked migration docs say to use 2.0.0

[Oleg Yukhnevich]

> I found it confusing that this release is actually 2.0.0-Beta but the linked migration docs say to use 2.0.0
Thanks for pointing! Fix has been already deployed!