Gradle Runner 2.0

[IgnatBeresnev]

Background

Dokka's current Gradle plugin has many problems:

• It is not idiomatic, not up to modern standard and does not follow best practices (see #2700).
• It's very difficult to use and confusing to configure, especially for beginners (confirmed by our UX researches and user interviews)
• It has a lot of internal technical debt, as multiple generations of maintainers worked on it without passing down the knowledge, and it wasn't looked after much this past year.
• There are things that do not cause trouble per se, but that we'd want to change given the chance (for example, Gradle integration tests).

Trying to improve the current plugin and resolve problems gradually proved to be difficult as it's gets overwhelming quick. Moreover, with this many changes needed, it would lead to multiple releases with noticeably broken backward compatibility.

At this point it seems like the best course of action is to just rip the bandaid off, and to redesign and reimplement the Gradle plugin from scratch, taking into consideration all of the experience and knowledge we have now.

This issue exists to keep track of progress and to provide updates to the community.

High-level goals

• Redesign the configuration DSL:
  • Use the knowledge we got from conducting UX researches and user interviews.
  • Comb through existing issues with the configuration tag and take them into account
  • Make sure the DSL respects project isolation and is configuration cache compatible from the get-go
  • Address our internal wants and wishes
• Make sure the new plugin is idiomatic and follows best practices, both on the surface and under the hood
• Significantly improve or even re-write user-facing documentation.

We won't be able to implement all feature requests and fix all the bugs, but we'll make sure to lay a solid foundation to address them in the future.

High-level plans

We plan to start with designing the new configuration DSL, and it'll take some thinking time and rounds of internal and external review. It's important to get it (mostly) right the first time around, as we want it to be very stable for at least the first couple of major releases after it's out.

As for re-writing the plugin internals, a regular contributor @aSemy started working on it in January (#2839), which grew into a separate project called Dokkatoo (double pun intended). Dokkatoo has been adopted by a number of big projects (including Gradle itself), and has proved itself to be very idiomatic and modern. We hope Dokkatoo will be contributed upstream into Dokka, laying the very foundation for the Gradle plugin 2.0.

We also plan to test the new plugin on a wide range of projects and platforms, with various Kotlin and Gradle versions, and to provide migration guides -- all to ease the transition as much as possible.

More specific details and plans will follow.

---

Milestone: milestone/28