Skip to content

fix: update gradle plugin documentation to gradle convention plugin #15

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ItsKev merged 1 commit into from
Feb 4, 2026
+114 −33
Merged

fix: update gradle plugin documentation to gradle convention plugin #15

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
64 changes: 47 additions & 17 deletions tools/gradle-plugin/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
---
title: "Overview"
description: "Gradle plugin bundle providing standardized build configurations for Grounds projects"

Check warning on line 3 in tools/gradle-plugin/index.mdx

View check run for this annotation

Mintlify / Mintlify Validation (grounds) - vale-spellcheck

tools/gradle-plugin/index.mdx#L3 

Did you really mean 'Gradle'?
---

The `library-gradle-plugin` is a Gradle plugin bundle that provides standardized build configurations for Grounds projects. It consolidates common setup tasks, dependency management, and build configurations to ensure consistency across all Grounds projects while reducing boilerplate configuration.
The `library-gradle-plugin` is a Gradle convention plugin bundle that provides standardized build configurations for Grounds projects. It consolidates common setup tasks, dependency management, and build configurations to ensure consistency across all Grounds projects while reducing boilerplate configuration.

Check warning on line 6 in tools/gradle-plugin/index.mdx

View check run for this annotation

Mintlify / Mintlify Validation (grounds) - vale-spellcheck

tools/gradle-plugin/index.mdx#L6 

Did you really mean 'Gradle'?

## Quick Links

Expand All @@ -19,37 +19,67 @@

## Getting Started

To get started with the Gradle plugin bundle:

Check warning on line 22 in tools/gradle-plugin/index.mdx

View check run for this annotation

Mintlify / Mintlify Validation (grounds) - vale-spellcheck

tools/gradle-plugin/index.mdx#L22 

Did you really mean 'Gradle'?

1. [Install the plugins](/tools/gradle-plugin/usage) in your project
2. Choose the appropriate plugin for your project type:
- Use Root Plugin for shared repository configuration
- Use Paper Plugin for Paper server plugins
- Use Velocity Plugin for Velocity proxy plugins
2. Apply the base conventions plugin with a version
3. Add the project-specific conventions (Paper, Velocity, Minestom, gRPC) as needed

Check warning on line 26 in tools/gradle-plugin/index.mdx

View check run for this annotation

Mintlify / Mintlify Validation (grounds) - vale-spellcheck

tools/gradle-plugin/index.mdx#L26 

Did you really mean 'Minestom'?

## Functionality

The plugin bundle consists of three main plugins, each providing specific functionality:
The plugin bundle consists of convention plugins, each providing specific functionality:

### Root Plugin (`gg.grounds.root`)
## Plugin Structure

- Applies standard plugins (maven-publish, Kotlin JVM, Kapt, Spotless)
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
```

### Base Conventions (`gg.grounds.base-conventions`)

- Applies standard plugins (Kotlin JVM, Kapt, Spotless)

Check warning on line 48 in tools/gradle-plugin/index.mdx

View check run for this annotation

Mintlify / Mintlify Validation (grounds) - vale-spellcheck

tools/gradle-plugin/index.mdx#L48 

Did you really mean 'Kapt'?
- Code formatting with Spotless (ktfmt, Google Style, 4-space indentation)

Check warning on line 49 in tools/gradle-plugin/index.mdx

View check run for this annotation

Mintlify / Mintlify Validation (grounds) - vale-spellcheck

tools/gradle-plugin/index.mdx#L49 

Did you really mean 'ktfmt'?
- Configures Maven Central repository for all projects
- Automatic Kotlin project configuration (Group: gg.grounds, version management, JVM Toolchain 25)
- Configures Maven Central repository
- Kotlin + Java toolchain configuration (JVM 25, Java 24)

Check warning on line 51 in tools/gradle-plugin/index.mdx

View check run for this annotation

Mintlify / Mintlify Validation (grounds) - vale-spellcheck

tools/gradle-plugin/index.mdx#L51 

Did you really mean 'toolchain'?
- Group/version defaults with optional `versionOverride` property
- JUnit Platform for tests with full exception output

Check warning on line 53 in tools/gradle-plugin/index.mdx

View check run for this annotation

Mintlify / Mintlify Validation (grounds) - vale-spellcheck

tools/gradle-plugin/index.mdx#L53 

Did you really mean 'JUnit'?

### Kotlin Conventions (`gg.grounds.kotlin-conventions`)

- Maven publishing to GitHub Packages
- Maven publication naming for root and subprojects

Check warning on line 58 in tools/gradle-plugin/index.mdx

View check run for this annotation

Mintlify / Mintlify Validation (grounds) - vale-spellcheck

tools/gradle-plugin/index.mdx#L58 

Did you really mean 'subprojects'?

### Paper Plugin (`gg.grounds.paper`)
### Paper Base Conventions (`gg.grounds.paper-base-conventions`)

- Adds Paper repository
- Shadow packaging configuration (Fat JAR)
- Optional Paper API dependency (configurable via extension)
- Automatic version replacement in plugin.yml
- Disables default `jar` task and wires `shadowJar` into `build`
- Standardized Shadow JAR naming

### Velocity Plugin (`gg.grounds.velocity`)
### Paper Conventions (`gg.grounds.paper-conventions`)

- Paper API dependency (compileOnly)

Check warning on line 69 in tools/gradle-plugin/index.mdx

View check run for this annotation

Mintlify / Mintlify Validation (grounds) - vale-spellcheck

tools/gradle-plugin/index.mdx#L69 

Did you really mean 'compileOnly'?
- Automatic version replacement in `plugin.yml`

### Velocity Conventions (`gg.grounds.velocity-conventions`)

- Adds Paper repository
- Shadow packaging configuration (Fat JAR)
- Optional Velocity API dependencies (compileOnly and kapt)

Check warning on line 74 in tools/gradle-plugin/index.mdx

View check run for this annotation

Mintlify / Mintlify Validation (grounds) - vale-spellcheck

tools/gradle-plugin/index.mdx#L74 

Did you really mean 'compileOnly'?

Check warning on line 74 in tools/gradle-plugin/index.mdx

View check run for this annotation

Mintlify / Mintlify Validation (grounds) - vale-spellcheck

tools/gradle-plugin/index.mdx#L74 

Did you really mean 'kapt'?
- Automatic generation of BuildInfo class with version for dynamic plugin versioning
- Automatic generation of `BuildInfo` class with version for dynamic plugin versioning

### Minestom Conventions (`gg.grounds.minestom-conventions`)

Check warning on line 77 in tools/gradle-plugin/index.mdx

View check run for this annotation

Mintlify / Mintlify Validation (grounds) - vale-spellcheck

tools/gradle-plugin/index.mdx#L77 

Did you really mean 'Minestom'?

- Minestom dependency

Check warning on line 79 in tools/gradle-plugin/index.mdx

View check run for this annotation

Mintlify / Mintlify Validation (grounds) - vale-spellcheck

tools/gradle-plugin/index.mdx#L79 

Did you really mean 'Minestom'?
- JVM target attribute pinned to 25 for resolved configurations

### gRPC Conventions (`gg.grounds.grpc-conventions`)

- Protobuf + gRPC dependencies

Check warning on line 84 in tools/gradle-plugin/index.mdx

View check run for this annotation

Mintlify / Mintlify Validation (grounds) - vale-spellcheck

tools/gradle-plugin/index.mdx#L84 

Did you really mean 'Protobuf'?
- Protobuf code generation with gRPC plugin

Check warning on line 85 in tools/gradle-plugin/index.mdx

View check run for this annotation

Mintlify / Mintlify Validation (grounds) - vale-spellcheck

tools/gradle-plugin/index.mdx#L85 

Did you really mean 'Protobuf'?
83 changes: 67 additions & 16 deletions tools/gradle-plugin/usage.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: "Usage"
description: "Step-by-step guide to install and configure the Gradle plugin bundle"

Check warning on line 3 in tools/gradle-plugin/usage.mdx

View check run for this annotation

Mintlify / Mintlify Validation (grounds) - vale-spellcheck

tools/gradle-plugin/usage.mdx#L3 

Did you really mean 'Gradle'?
---

The plugins are published to GitHub Packages. To use them, you need to configure your project to access the GitHub Packages Maven repository.
Expand All @@ -9,7 +9,7 @@

Before installing the plugins, ensure you have:

- Gradle 7.0 or higher

Check warning on line 12 in tools/gradle-plugin/usage.mdx

View check run for this annotation

Mintlify / Mintlify Validation (grounds) - vale-spellcheck

tools/gradle-plugin/usage.mdx#L12 

Did you really mean 'Gradle'?
- A GitHub account with access to the `groundsgg` organization
- A GitHub personal access token with `read:packages` permission

Expand All @@ -17,7 +17,7 @@

1. Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
2. Click "Generate new token (classic)"
3. Give it a descriptive name (e.g., "Gradle Packages Access")

Check warning on line 20 in tools/gradle-plugin/usage.mdx

View check run for this annotation

Mintlify / Mintlify Validation (grounds) - vale-spellcheck

tools/gradle-plugin/usage.mdx#L20 

Did you really mean 'Gradle'?
4. Select the `read:packages` scope
5. Generate the token and copy it immediately

Expand All @@ -25,7 +25,7 @@
Store your token securely. You won't be able to see it again after leaving the page.
</Warning>

## Step 2: Configure Gradle Properties

Check warning on line 28 in tools/gradle-plugin/usage.mdx

View check run for this annotation

Mintlify / Mintlify Validation (grounds) - vale-spellcheck

tools/gradle-plugin/usage.mdx#L28 

Did you really mean 'Gradle'?

Add your GitHub credentials to `~/.gradle/gradle.properties`:

Expand Down Expand Up @@ -59,35 +59,65 @@

## Step 4: Apply the Plugin

Apply the appropriate plugin in your `build.gradle.kts` file based on your project type:
Apply the base conventions plugin with a version, then add the conventions that match your project type:

### Root Plugin
### Base Conventions (required)

For root projects or shared configurations:
Apply once per project (usually in the root project):

```kotlin build.gradle.kts
plugins {
id("gg.grounds.root") version "0.1.1"
id("gg.grounds.base-conventions") version "0.3.0"
}
```

### Paper Plugin
### Kotlin Conventions

For Kotlin projects (typically shared/common modules):

```kotlin build.gradle.kts
plugins {
id("gg.grounds.kotlin-conventions")
}
```
Comment on lines +74 to +82
Copy link

Copilot AI Jan 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).

Copilot uses AI. Check for mistakes.

### Paper Conventions

For Paper server plugin projects:

```kotlin build.gradle.kts
plugins {
id("gg.grounds.paper") version "0.1.1"
id("gg.grounds.paper-conventions")
}
```

### Velocity Plugin
### Velocity Conventions

For Velocity proxy plugin projects:

```kotlin build.gradle.kts
plugins {
id("gg.grounds.velocity") version "0.1.1"
id("gg.grounds.velocity-conventions")
}
```

### Minestom Conventions

Check warning on line 104 in tools/gradle-plugin/usage.mdx

View check run for this annotation

Mintlify / Mintlify Validation (grounds) - vale-spellcheck

tools/gradle-plugin/usage.mdx#L104 

Did you really mean 'Minestom'?

For Minestom server plugin projects:

Check warning on line 106 in tools/gradle-plugin/usage.mdx

View check run for this annotation

Mintlify / Mintlify Validation (grounds) - vale-spellcheck

tools/gradle-plugin/usage.mdx#L106 

Did you really mean 'Minestom'?

```kotlin build.gradle.kts
plugins {
id("gg.grounds.minestom-conventions")
}
```

### gRPC Conventions

For gRPC projects:

```kotlin build.gradle.kts
plugins {
id("gg.grounds.grpc-conventions")
}
```

Expand All @@ -99,7 +129,22 @@
./gradlew tasks --all
```

You should see tasks provided by the plugin in the output. For example, with the root plugin, you'll see Spotless formatting tasks.
You should see tasks provided by the plugin in the output. For example, with base conventions, you'll see Spotless formatting tasks.

## Overriding Paper, Velocity, or Minestom Versions

Check warning on line 134 in tools/gradle-plugin/usage.mdx

View check run for this annotation

Mintlify / Mintlify Validation (grounds) - vale-spellcheck

tools/gradle-plugin/usage.mdx#L134 

Did you really mean 'Minestom'?

Your project can request a higher Paper, Velocity, or Minestom version by declaring it in dependencies. Lower versions are not supported.

Check warning on line 136 in tools/gradle-plugin/usage.mdx

View check run for this annotation

Mintlify / Mintlify Validation (grounds) - vale-spellcheck

tools/gradle-plugin/usage.mdx#L136 

Did you really mean 'Minestom'?

- Current Paper version: `1.21.11-R0.1-SNAPSHOT`
- Current Velocity version: `3.4.0-SNAPSHOT`
- Current Minestom version: `2026.01.08-1.21.11`

Check warning on line 140 in tools/gradle-plugin/usage.mdx

View check run for this annotation

Mintlify / Mintlify Validation (grounds) - vale-spellcheck

tools/gradle-plugin/usage.mdx#L140 

Did you really mean 'Minestom'?

```kotlin
dependencies {
// Overrides the Paper version with a higher one
compileOnly("io.papermc.paper:paper-api:1.21.12-R0.1-SNAPSHOT")
}
```

## Multi-Module Projects

Expand All @@ -123,25 +168,31 @@
include("paper-plugin", "velocity-plugin")
```

Then apply the root plugin in the root `build.gradle.kts`:
Then apply the base conventions in the root `build.gradle.kts`:

```kotlin build.gradle.kts
plugins {
id("gg.grounds.root") version "0.1.1"
id("gg.grounds.base-conventions") version "0.3.0"
}
```

And apply specific plugins in each subproject's `build.gradle.kts`:
And apply specific conventions in each subproject's `build.gradle.kts`:

Check warning on line 179 in tools/gradle-plugin/usage.mdx

View check run for this annotation

Mintlify / Mintlify Validation (grounds) - vale-spellcheck

tools/gradle-plugin/usage.mdx#L179 

Did you really mean 'subproject's'?

```kotlin paper-plugin/build.gradle.kts
plugins {
id("gg.grounds.paper") version "0.1.1"
id("gg.grounds.paper-conventions")
}
```

```kotlin velocity-plugin/build.gradle.kts
plugins {
id("gg.grounds.velocity") version "0.1.1"
id("gg.grounds.velocity-conventions")
}
```

```kotlin grpc-module/build.gradle.kts
plugins {
id("gg.grounds.grpc-conventions")
}
```

Comment on lines +193 to 198
Copy link

Copilot AI Jan 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Suggested change
```kotlin grpc-module/build.gradle.kts
plugins {
id("gg.grounds.grpc-conventions")
}
```

Copilot uses AI. Check for mistakes.
Expand All @@ -152,12 +203,12 @@
If you encounter authentication errors:

1. Verify your GitHub token has `read:packages` permission
2. Check that `github.user` and `github.token` are correctly set in your Gradle properties

Check warning on line 206 in tools/gradle-plugin/usage.mdx

View check run for this annotation

Mintlify / Mintlify Validation (grounds) - vale-spellcheck

tools/gradle-plugin/usage.mdx#L206 

Did you really mean 'Gradle'?
3. Ensure the token hasn't expired

### Plugin Not Found

If Gradle cannot find the plugin:

Check warning on line 211 in tools/gradle-plugin/usage.mdx

View check run for this annotation

Mintlify / Mintlify Validation (grounds) - vale-spellcheck

tools/gradle-plugin/usage.mdx#L211 

Did you really mean 'Gradle'?

1. Verify the repository URL is correct: `https://maven.pkg.github.com/groundsgg/*`
2. Check that `gradlePluginPortal()` is included in the repositories list
Expand All @@ -165,11 +216,11 @@

### Version Updates

To update to a newer version, change the version number in your `build.gradle.kts`:
To update to a newer version, change the version number only on `gg.grounds.base-conventions`:

```kotlin build.gradle.kts
plugins {
id("gg.grounds.root") version "0.1.1" // Update this version
id("gg.grounds.base-conventions") version "0.3.0" // Update this version
}
```

Expand Down