Simplifying the Plugin-Publish Plugin

July 18, 2022

Configuring the publication of Gradle plugins to the Portal happens with the help of the Plugin-Publish plugin. The recently released version 1.0.0 of the plugin significantly improves the process by having stronger opinions and a more straightforward configuration.

Stronger Conventions

Gradle plugin development has a long history and has gradually evolved to use helper plugins to aid you with setting up your plugin project. The most important ones:

Gradle Plugin Development plugin (java-gradle-plugin)
Maven Publish plugin (maven-publish)

The Plugin-Publish plugin shares this long history, and it ended up supporting all the various combinations of helper plugins. This results in too many ways of publishing plugins, and too many configuration options, with some having hard-to-understand semantics depending on the exact setup.

For example, publication metadata can be generated via the maven-publish plugin or in other, ad-hoc ways. Depending on this, both plugin and marker GAV coordinates can vary, with surprising effects.

Version 1.0.0 of the Plugin-Publish plugin addresses these issues by tightening and enforcing the conventions. The main helper plugins are always auto-applied:

maven-publish is always used for generating the publication metadata (Maven POM & Gradle Module Metadata).
java-gradle-plugin is always applied and used as a base for plugin definitions; as a consequence, the gradlePlugin block is now mandatory and the pluginBundle block has been trimmed down to remove all duplication.

Unambiguous configuration

When configuring the publication of plugins, each property of the end result should have a single way of being specified.

To ensure that’s the case, version 1.0.0 of the Plugin-Publish plugin is removing the pluginBundle.plugins block, as it was duplicating gradlePlugin.plugins.

Unfortunately, the duplication is not (yet) perfect, so the pluginBundle.pluginTags map needs to be added to be able to define different tags for plugins published together. The more elegant solution is to allow tags to be specified in the elements of the gradlePlugin.plugins block, but this will be possible only starting with Gradle 7.6.

See an example here to be updated with further improvements once Gradle 7.6 is out.

Clearly defined interactions

Version 1.0.0 specifies (and automates) the way the Plugin-Publish plugin interacts with other frequently used plugins:

If the Signing plugin is applied, then all published artifacts of the plugin will be automatically signed.
If the Shadow plugin is applied, then the plugin’s main jar will be the shadow jar, as configured by the Shadow plugin.

Should those plugins be applied, the user receives a notification on the console about the automatic configuration they trigger.

Breaking changes

In the spirit of stronger conventions and simplified configuration version 1.0.0 also comes with some breaking changes.

The lowest Gradle version supported by the Plugin-Publish plugin becomes 4.10.3. It has been 3.5.1 previously.

Making the maven-publish plugin mandatory also results in the mavenCoordinates and withDependencies blocks being completely removed. The functionality they offered is no longer needed or meaningful.

Documentation

The main documentation for using the com.gradle.plugin-publish plugin is on the Plugin Portal. There is additional documentation in the Gradle Manual, but please note that the manual will focus on this new version of the com.gradle.plugin-publish only starting with Gradle 7.6.

Conclusion

With this simplified and clarified setup, we encourage plugin authors to adopt this new version as soon as possible.

We are looking for your feedback on our Community Slack or the Gradle Forums. Don’t hesitate to contact us both if you encounter problems with the new version or if you want to express your support for the work we do.