fix: update gradle plugin documentation to gradle convention plugin #15
Conversation
There was a problem hiding this comment.
Pull request overview
Updates the Gradle plugin documentation to reflect the move from “project plugins” (root/paper/velocity) to a Gradle convention plugin bundle with a base-conventions plugin and layered convention plugins.
Changes:
- Rewrites usage instructions to apply
gg.grounds.base-conventionswith a version and then add project-specific convention plugins. - Expands the documented convention set (Kotlin, Paper, Velocity, Minestom, gRPC) and adds version override guidance.
- Updates the overview page with a plugin layering diagram and updated feature breakdown.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| tools/gradle-plugin/usage.mdx | Updates installation/apply instructions and adds version override + multi-module examples for convention plugins. |
| tools/gradle-plugin/index.mdx | Reframes the bundle as convention plugins and documents the layering/feature set (including a Mermaid diagram). |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| ### Kotlin Conventions | ||
|
|
||
| For Kotlin projects (typically shared/common modules): | ||
|
|
||
| ```kotlin build.gradle.kts | ||
| plugins { | ||
| id("gg.grounds.kotlin-conventions") | ||
| } | ||
| ``` |
There was a problem hiding this comment.
The examples apply gg.grounds.kotlin-conventions / paper-conventions / etc without a version, but the doc doesn’t show any place where Gradle would learn that version (e.g., pluginManagement { plugins { ... } }, a root plugins { ... apply false }, or a version catalog). As written, these snippets will fail to resolve the plugins. Update the docs to include a single-source version declaration for all convention plugin IDs (or show versions on each plugin).
| ```kotlin grpc-module/build.gradle.kts | ||
| plugins { | ||
| id("gg.grounds.grpc-conventions") | ||
| } | ||
| ``` | ||
|
|
There was a problem hiding this comment.
The multi-module example shows a grpc-module/build.gradle.kts, but settings.gradle.kts only includes paper-plugin and velocity-plugin. Add include("grpc-module") (or remove the gRPC subproject example) so the sample project configuration is internally consistent.
| ```kotlin grpc-module/build.gradle.kts | |
| plugins { | |
| id("gg.grounds.grpc-conventions") | |
| } | |
| ``` |
| The convention plugins build on each other. Base conventions sit at the bottom, Kotlin conventions add publishing, and the platform-specific conventions layer on top. | ||
|
|
||
| ```mermaid | ||
| graph TB | ||
| kotlin["kotlin-conventions"] --> base["base-conventions"] | ||
| minestom["minestom-conventions"] --> kotlin | ||
| paperbase["paper-base-conventions"] --> kotlin | ||
| grpc["grpc-conventions"] --> kotlin | ||
| paper["paper-conventions"] --> paperbase | ||
| velocity["velocity-conventions"] --> paperbase |
There was a problem hiding this comment.
The Mermaid diagram arrows appear reversed relative to the description (“Base conventions sit at the bottom, Kotlin conventions add publishing, and the platform-specific conventions layer on top”). In Mermaid, A --> B reads as A points to/depends on B, so kotlin --> base implies Kotlin depends on Base (ok) but then paperbase --> kotlin implies Paper Base depends on Kotlin (also ok) while paper --> paperbase implies Paper depends on Paper Base (ok). However the labels omit the gg.grounds.* prefixes and the directionality is ambiguous for readers; consider rewriting the diagram to clearly indicate dependency direction (e.g., base --> kotlin --> paper-base --> paper) and match the text exactly.
| The convention plugins build on each other. Base conventions sit at the bottom, Kotlin conventions add publishing, and the platform-specific conventions layer on top. | |
| ```mermaid | |
| graph TB | |
| kotlin["kotlin-conventions"] --> base["base-conventions"] | |
| minestom["minestom-conventions"] --> kotlin | |
| paperbase["paper-base-conventions"] --> kotlin | |
| grpc["grpc-conventions"] --> kotlin | |
| paper["paper-conventions"] --> paperbase | |
| velocity["velocity-conventions"] --> paperbase | |
| The convention plugins build on each other: base conventions sit at the bottom, Kotlin conventions add publishing, and the platform-specific conventions layer on top. In the diagram below, arrows point from each convention plugin to the one it depends on. | |
| ```mermaid | |
| graph TD | |
| kotlin["gg.grounds.kotlin-conventions"] --> base["gg.grounds.base-conventions"] | |
| minestom["gg.grounds.minestom-conventions"] --> kotlin | |
| paperbase["gg.grounds.paper-base-conventions"] --> kotlin | |
| grpc["gg.grounds.grpc-conventions"] --> kotlin | |
| paper["gg.grounds.paper-conventions"] --> paperbase | |
| velocity["gg.grounds.velocity-conventions"] --> paperbase |
Pull Request
Description
Type of Change
Related Issues
None
Testing
Checklist