Gradle Plugins, Core Plugins, Community Plugins, Convention Plugins, and Plugin Management: Configuration, Design Choices, and Tradeoffs

1. Design principle: centralize policy, not accidental coupling

Centralization is useful when several projects genuinely share one invariant—Java release, formatting policy, test conventions, publication metadata, or compiler warnings. It is harmful when one root script reaches into every project and silently assumes plugins, tasks, or layouts that do not belong there.

A convention plugin gives shared policy a name and an application boundary. A project applies the convention because it participates in that policy; unrelated projects remain independent.

2. Repeated configuration versus convention plugin

3. buildSrc versus included build-logic

Both can host precompiled or binary plugins. buildSrc is automatically compiled and placed on the main build’s classpath. An explicit included build is independently structured and included through settings. Gradle’s current best-practice guidance favors an included build-logic composite build for scalable build logic because its boundary is explicit and changes can be more isolated.

4. Community plugin convenience versus supply-chain and release risk

A community plugin can remove large amounts of custom code, but it adds a publisher, release cadence, repository, transitive plugin implementation dependencies, compatibility matrix, and update process to your build trust graph. Evaluate it like executable infrastructure code.

5. Centralized plugin versions versus local autonomy

pluginManagement.plugins can establish a default version for a plugin ID across a build. That improves consistency but should remain an explicit policy, not a hidden constraint. A module that genuinely requires a different plugin version may need a separate build boundary or an intentionally documented compatibility exception.

Do not use dynamic selectors as a production shortcut such as 8.+. Reproducibility requires a reviewed immutable version decision.

pluginManagement {
    plugins {
        id("com.diffplug.spotless") version "8.10.0"
    }
}

6. Public API compatibility is part of plugin design

Repository-owned plugins should prefer Gradle’s documented public API and Provider/task configuration-avoidance patterns. A plugin that imports internal implementation classes can compile today and fail after a Wrapper upgrade. A plugin that eagerly realizes all tasks can preserve correctness but increase configuration time and block future optimizations.

That makes a Gradle upgrade a two-sided compatibility event: upgrade the engine and validate the plugins/build logic that execute inside it.

7. Keep adjacent configuration systems separate

8. Worked scenario: six JVM modules with two policy families

Suppose a repository contains four service modules and two reusable libraries. All six require Java 17 and compiler encoding. Only services need application packaging. All Java modules need Spotless, but a documentation-only project does not.

A maintainable design is:

1. academy.java-base convention: Java plugin, toolchain, compiler/test defaults.
2. academy.java-library convention: applies the base convention plus java-library.
3. academy.java-service convention: applies the base convention plus application.
4. academy.formatting convention: applies/configures the pinned Spotless implementation for opted-in modules.
5. Settings owns external plugin repository/version policy; each project applies only the conventions it needs.

This design centralizes invariants while preserving explicit project roles.

9. Decision table

10. Performance and CI throughput: measure configuration effects, do not assume

Convention plugins can improve maintainability without automatically improving build speed. Poorly authored convention logic can eagerly realize tasks or read environment/files during configuration. When performance matters, compare configuration time, task realization, configuration-cache compatibility, and clean/warm runs under controlled conditions. Chapter 25 will go deeper on Gradle performance; here the rule is to keep plugin logic lazy and evidence-driven.

11. Upgrade cost belongs in the original architecture decision

A centralized plugin version is easy to update once but can affect many projects at once. Local versions isolate blast radius but invite drift. Convention plugins simplify consistent fixes but become another codebase requiring tests and API discipline. Document the intended owner and rollout method when the plugin is introduced—not after the first broken upgrade.

Knowledge check

12. Bridge to diagnostics

Lesson 4 now breaks these policies deliberately: a missing plugin repository/version, eager convention logic, internal-API dependence, and inconsistent subproject application. The goal is to diagnose from plugin source/model evidence—not to clear caches until the build happens to pass.

Official references and version notes

• Gradle 9.7.1 Release Notes — pinned Gradle baseline for this chapter.
• Introduction to Plugins and Working with Plugins — core/community/local plugin sources, plugins DSL, plugin management, and resolution.
• Convention Plugins and Precompiled Script Plugins.
• Best Practices for Structuring Builds — convention plugins and the current preference for an included build-logic build over repeated cross-project configuration.
• Composite Builds — included plugin builds and plugin resolution.
• PluginManagementSpec — plugin repositories, default plugin versions, resolution strategy, and included plugin builds.
• Task Configuration Avoidance — relevant when convention/plugin code contributes tasks.
• Gradle Plugin Portal: com.diffplug.spotless — controlled community-plugin example; version 8.10.0 was published August 17, 2026 and is configuration-cache compatible according to the Portal.

Version snapshot: Generated August 24, 2026 with Gradle 9.7.1, JDK 21 as the Gradle runtime, Java 17 as the course JVM target, and com.diffplug.spotless 8.10.0 as the one external community-plugin example. Re-check plugin versions and compatibility before adopting them in production.