chore: add individual description txt file for each plugin (#29)

* chore: add individual description txt file for each plugin
* chore: add tag 'hiero'
* chore: add more documentation to Readme
* chore: describe expected project structure with example

---------

Signed-off-by: Jendrik Johannes <[email protected]>

README.md

@@ -1,6 +1,90 @@
 # Hiero Gradle Conventions
 
-Gradle convention plugins used by Hiero projects.
+Gradle [convention plugins](https://docs.gradle.org/current/samples/sample_convention_plugins.html) used by Hiero projects.
+
+Any Gradle-based Java project that uses the Java Module System (JPMS) may use these convention plugins.
+That includes projects that are not part of the Hiero organisation. The conventions follow latest Gradle best practices
+and ensure compatibility with performance features such as the
+[Remote Build Cache](https://docs.gradle.com/build-cache-node/) and the
+[Configuration Cache](https://docs.gradle.org/current/userguide/configuration_cache.html).
+The convention plugins pull in a [curated set of third-party Gradle plugins](build.gradle.kts#L18-L34)
+that also support these features and are compatible with the latest Gradle version.
+
+## Using the Convention Plugins
+
+Apply the entry point plugin `org.hiero.gradle.build` in the `settings.gradle.kts` file.  Additionally, define where
+Modules (subprojects) are located in the directory hierarchy by using the `javaModules { ... }` notation
+(which is provided by the [org.gradlex.java-module-dependencies](https://github.com/gradlex-org/java-module-dependencies?tab=readme-ov-file#project-structure-definition-when-using-this-plugin-as-settings-plugin) plugin).
+
+```
+// settings.gradle.kts
+plugins {
+    id("org.hiero.gradle.build") version "0.1.0"
+}
+
+// Define location of Modules (subprojects)
+javaModules {
+    directory("product-a") { // searches for 'module-info.java' in subfolders of 'product-a'
+      group = "org.example.product-a"
+    }
+}
+```
+
+In each Module (subproject), apply one of the `org.hiero.gradle.module.*` plugins and, if desired, additional
+`org.hiero.gradle.feature.*` plugins.
+
+For example, to define a Library Module that also provides _test fixtures_ and has _JMH benchmarks_, the plugins block
+should look like this:
+
+```
+plugins {
+    id("org.hiero.gradle.module.library")
+    id("org.hiero.gradle.feature.test-fixtures")
+    id("org.hiero.gradle.feature.benchmark")
+}
+```
+
+### Project structure
+
+There is a [minimal example](example) setup.
+
+```
+├── settings.gradle.kts                          // Entriy point (see above) 
+├── gradle.properties                            // Turn on Gradle caches
+├── gradle/aggregation/build.gradle.kts          // List of all product/service modules for consistent resolution
+├── gradle/toolchain-versions.properties         // JDK version (and other tools if applicable)
+├── gradle/wrapper/gradle-wrapper.properties     // Gradle version (defined through Gradle wrapper)
+├── hiero-dependency-versions/build.gradle.kts   // Versions of 3rd-party modules
+├── product-a                                    // Folder containing all modules of 'product-a'
+│   ├── module-app                               // Example of a Application module
+│   │   ├── build.gradle.kts                     // Select which build features to use in 'plugins {}' (see above) 
+│   │   └── src/main/java/module-info.java       // Define dependencies to other modules
+│   ├── module-lib                               // Example of a Library module
+│   │   ├── build.gradle.kts                     // Select which build features to use in 'plugins {}' (see above) 
+│   │   └── src/main/java/module-info.java       // Define dependencies to other modules
+│   ├── description.txt                          // Description of the product (for published metadata)
+│   └── developers.properties                    // Developers of the product (for published metadata)
+└── version.txt                                  // Version of all modules/products
+```
+
+## List of Convention Plugins
+
+The plugins are written in Gradle's Kotlin DSL and are found in [src/main/kotlin](src/main/kotlin).
+Each plugin has a short description located in [src/main/descriptions](src/main/descriptions).
+
+Each plugin configures a certain build aspect, following this naming pattern:
+
+- `org.hiero.gradle.base.*` _Base_ plugins need to be used in all Modules to establish a certain foundation
+  for the setup. For example, the same dependency management configuration should be applied everywhere to
+  consistently use the same 3rd party libraries everywhere.
+- `org.hiero.gradle.feature.*` Each _feature_ plugin configures one aspect of building the software –
+  like compiling code or testing code.
+- `org.hiero.gradle.check.*` _Check_ plugins help with keeping the software maintainable over time.
+  They check things like the dependency setup or code formatting.
+- `org.hiero.gradle.report.*` _Report_ plugins configure the export of information into reports that can be picked
+up by other systems - e.g. for code coverage reporting.
+- `org.hiero.gradle.module.*` _Module_ plugins combine plugins from all categories above to define
+  _Module Types_ that are then used in the `build.gradle.kts` files of the individual Modules of our software.
 
 ## Contributing
 

build.gradle.kts

@@ -38,9 +38,22 @@ gradlePlugin {
     website = "https://github.com/hiero-ledger/hiero-gradle-conventions"
     vcsUrl = "https://github.com/hiero-ledger/hiero-gradle-conventions"
     plugins.configureEach {
-        description = project.description
+        val descriptionFile = layout.projectDirectory.file("src/main/descriptions/${id}.txt")
+        description =
+            providers
+                .fileContents(descriptionFile)
+                .asText
+                .orElse(
+                    provider {
+                        throw RuntimeException(
+                            "File not found ${descriptionFile.asFile.absolutePath}"
+                        )
+                    }
+                )
+                .get()
+                .trim()
         @Suppress("UnstableApiUsage")
-        tags = listOf("conventions", "java", "modules", "jpms")
+        tags = listOf("hiero", "conventions", "java", "modules", "jpms")
     }
 
     plugins.configureEach { displayName = name }

example/gradle.properties

@@ -0,0 +1,3 @@
+org.gradle.jvmargs=-Dfile.encoding=UTF-8 -Xmx2g
+org.gradle.caching=true
+org.gradle.configuration-cache=true

example/gradle/aggregation/build.gradle.kts

@@ -0,0 +1,9 @@
+// SPDX-License-Identifier: Apache-2.0
+plugins {
+    id("org.hiero.gradle.base.lifecycle")
+    id("org.hiero.gradle.report.code-coverage")
+}
+
+dependencies {
+    implementation(project(":module-app"))
+}

example/gradle/toolchain-versions.properties

@@ -0,0 +1 @@
+jdk=17.0.12

example/gradle/wrapper/gradle-wrapper.properties

@@ -0,0 +1,7 @@
+distributionBase=GRADLE_USER_HOME
+distributionPath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.11.1-bin.zip
+networkTimeout=10000
+validateDistributionUrl=true
+zipStoreBase=GRADLE_USER_HOME
+zipStorePath=wrapper/dists

example/hiero-dependency-versions/build.gradle.kts

@@ -0,0 +1,11 @@
+// SPDX-License-Identifier: Apache-2.0
+plugins {
+    id("org.hiero.gradle.base.lifecycle")
+    id("org.hiero.gradle.base.jpms-modules")
+}
+
+dependencies.constraints {
+    api("com.fasterxml.jackson.core:jackson-databind:2.16.0") {
+        because("com.fasterxml.jackson.databind")
+    }
+}

example/product-a/description.txt

@@ -0,0 +1 @@
+The amazing product-a

example/product-a/developers.properties

@@ -0,0 +1 @@
+example[email protected]

example/product-a/module-app/build.gradle.kts

@@ -0,0 +1,4 @@
+// SPDX-License-Identifier: Apache-2.0
+plugins { id("org.hiero.gradle.module.application") }
+
+application { mainClass = "org.hiero.product.module.app.App" }

example/product-a/module-app/src/main/java/module-info.java

@@ -0,0 +1,4 @@
+// SPDX-License-Identifier: Apache-2.0
+module org.hiero.product.module.app {
+    requires org.hiero.product.module.lib;
+}

example/product-a/module-app/src/main/java/org/hiero/product/module/app/App.java

@@ -0,0 +1,11 @@
+// SPDX-License-Identifier: Apache-2.0
+package org.hiero.product.module.app;
+
+import org.hiero.product.module.lib.ModuleLib;
+
+public class App {
+
+    public static void main(String[] args) {
+        new ModuleLib().use();
+    }
+}

example/product-a/module-lib/build.gradle.kts

@@ -0,0 +1,2 @@
+// SPDX-License-Identifier: Apache-2.0
+plugins { id("org.hiero.gradle.module.library") }

example/product-a/module-lib/src/main/java/module-info.java

@@ -0,0 +1,6 @@
+// SPDX-License-Identifier: Apache-2.0
+module org.hiero.product.module.lib {
+    requires com.fasterxml.jackson.databind;
+
+    exports org.hiero.product.module.lib;
+}

example/product-a/module-lib/src/main/java/org/hiero/product/module/lib/ModuleLib.java

@@ -0,0 +1,10 @@
+// SPDX-License-Identifier: Apache-2.0
+package org.hiero.product.module.lib;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+
+public class ModuleLib {
+    public void use() {
+        new ObjectMapper();
+    }
+}

example/settings.gradle.kts

@@ -0,0 +1,6 @@
+// SPDX-License-Identifier: Apache-2.0
+plugins { id("org.hiero.gradle.build") version "0.1.0" }
+
+rootProject.name = "example-repository"
+
+javaModules { directory("product-a") { group = "org.example.product-a" } }

example/version.txt

@@ -0,0 +1 @@
+1.0

src/main/descriptions/org.hiero.gradle.base.jpms-modules.txt

@@ -0,0 +1 @@
+Adds a 'module-info.class' to Java libraries that do not yet provide it

src/main/descriptions/org.hiero.gradle.base.lifecycle.txt

@@ -0,0 +1 @@
+Tweaks lifecycle task setup: add quality check lifecycle tasks and remove some tasks from 'build' group

src/main/descriptions/org.hiero.gradle.base.version.txt

@@ -0,0 +1 @@
+Reads the project version from a 'version.txt' file located in the build root directory

src/main/descriptions/org.hiero.gradle.build.txt

@@ -0,0 +1 @@
+Entry point settings plugin that applies a basic set of 'org.hiero.gradle' convention plugins to the build and to all subprojects

src/main/descriptions/org.hiero.gradle.check.dependencies.txt

@@ -0,0 +1 @@
+Conventions for 'com.autonomousapps.dependency-analysis'

src/main/descriptions/org.hiero.gradle.check.javac-lint.txt

@@ -0,0 +1 @@
+Conventions for the linting features (-Xlint) of 'javac' that run as part of each 'compileJava' task

src/main/descriptions/org.hiero.gradle.check.spotless-java.txt

@@ -0,0 +1 @@
+Conventions for 'com.diffplug.spotless' with Palantir Java format and Apache-2.0 license

src/main/descriptions/org.hiero.gradle.check.spotless-kotlin.txt

@@ -0,0 +1 @@
+Conventions for 'com.diffplug.spotless' with ktfmt Kotlin format and Apache-2.0 license

src/main/descriptions/org.hiero.gradle.check.spotless-markdown.txt

@@ -0,0 +1 @@
+Conventions for 'com.diffplug.spotless' with flexmark Markdown format

src/main/descriptions/org.hiero.gradle.check.spotless-misc.txt

@@ -0,0 +1 @@
+Conventions for 'com.diffplug.spotless' for whitespace and newline formatting of plain text files

src/main/descriptions/org.hiero.gradle.check.spotless-yaml.txt

@@ -0,0 +1 @@
+Conventions for 'com.diffplug.spotless' with Prettier YAML format and Apache-2.0 license

src/main/descriptions/org.hiero.gradle.check.spotless.txt

@@ -0,0 +1 @@
+Conventions for 'com.diffplug.spotless' as part of the qualityCheck lifecycle

src/main/descriptions/org.hiero.gradle.feature.antlr.txt

@@ -0,0 +1 @@
+Conventions for 'antlr' that add missing task dependencies when integrating with other plugins

src/main/descriptions/org.hiero.gradle.feature.benchmark.txt

@@ -0,0 +1 @@
+Conventions for 'me.champeau.jmh' to use it in JPMS projects

src/main/descriptions/org.hiero.gradle.feature.build-cache.txt

@@ -0,0 +1 @@
+Standard configuration for a remote build cache that is pushed to from CI and pulled from everywhere

src/main/descriptions/org.hiero.gradle.feature.git-properties-file.txt

@@ -0,0 +1 @@
+Adds a 'git.properties' file with 'git.commit.id' entries to the Jar and makes sure the file is ignored in classpath normalization

src/main/descriptions/org.hiero.gradle.feature.java-compile.txt

@@ -0,0 +1 @@
+Conventions for reproducible Java Module compilation: applies 'org.gradlex.reproducible-builds' and ensures that an exact JDK version is configured and used

src/main/descriptions/org.hiero.gradle.feature.java-doc.txt

@@ -0,0 +1 @@
+Conventions for 'javadoc' that configures '-Xdoclint:all,-missing' and turns warnings into errors

src/main/descriptions/org.hiero.gradle.feature.java-execute.txt

@@ -0,0 +1 @@
+Conventions to make JavaExec tasks work with configuration cache in IntelliJ

src/main/descriptions/org.hiero.gradle.feature.protobuf.txt

@@ -0,0 +1 @@
+Conventions for 'com.google.protobuf' with 'grpc' plugin using versions from a platform project

src/main/descriptions/org.hiero.gradle.feature.publish-artifactregistry.txt

@@ -0,0 +1 @@
+Conventions for 'com.google.cloud.artifactregistry.gradle-plugin' to publish to GCP Artifact Registry repositories

src/main/descriptions/org.hiero.gradle.feature.publish-gradle-plugin-portal.txt

@@ -0,0 +1 @@
+Conventions for 'com.gradle.plugin-publish' to publish to the Gradle Plugin Portal

src/main/descriptions/org.hiero.gradle.feature.publish-maven-central.root.txt

@@ -0,0 +1 @@
+Conventions for 'io.github.gradle-nexus.publish-plugin' to publish to Maven Central and filter which modules are published through the '-PpublishingPackageGroup' parameter (root project plugin)

src/main/descriptions/org.hiero.gradle.feature.publish-maven-central.txt

@@ -0,0 +1 @@
+Conventions for 'io.github.gradle-nexus.publish-plugin' to publish to Maven Central and filter which modules are published through the '-PpublishingPackageGroup' parameter (subproject plugin)

src/main/descriptions/org.hiero.gradle.feature.publish-maven-repository.txt

@@ -0,0 +1 @@
+Conventions for 'maven-publish' that configure signing and add additional metadata to POM files

src/main/descriptions/org.hiero.gradle.feature.repositories.txt

@@ -0,0 +1 @@
+Configures a set of standard repositories for dependency resolution including Maven Central

src/main/descriptions/org.hiero.gradle.feature.rust.txt

@@ -0,0 +1 @@
+Add support for installing Rust toolchains and cross-compiling Rust source code

src/main/descriptions/org.hiero.gradle.feature.test-fixtures.txt

@@ -0,0 +1 @@
+Conventions for 'java-test-fixtures' that configures test fixtures support without publishing the fixtures

src/main/descriptions/org.hiero.gradle.feature.test-hammer.txt

@@ -0,0 +1 @@
+Adds a test suite called 'hammer'

src/main/descriptions/org.hiero.gradle.feature.test-integration.txt

@@ -0,0 +1 @@
+Adds a test suite called 'integration'

src/main/descriptions/org.hiero.gradle.feature.test-multios.txt

@@ -0,0 +1 @@
+Adds 'os.name' and 'os.arch' as inputs to the 'test' task

src/main/descriptions/org.hiero.gradle.feature.test-time-consuming.txt

@@ -0,0 +1 @@
+Adds a test suite called 'timeConsuming'

src/main/descriptions/org.hiero.gradle.feature.test-timing-sensitive.txt

@@ -0,0 +1 @@
+Adds a test suite called 'timingSensitive'

src/main/descriptions/org.hiero.gradle.feature.test.txt

@@ -0,0 +1 @@
+Conventions for the 'test' task that configure JUnit 5, memory settings and parallelism

src/main/descriptions/org.hiero.gradle.feature.versioning.txt

@@ -0,0 +1 @@
+Adds help tasks for updating the version.txt file

src/main/descriptions/org.hiero.gradle.module.application.txt

@@ -0,0 +1 @@
+Convention plugin that applies the minimal of set 'org.hiero.gradle' convention plugins necessary to build a Java application module

src/main/descriptions/org.hiero.gradle.module.gradle-plugin.txt

@@ -0,0 +1 @@
+Convention plugin that applies the minimal of set 'org.hiero.gradle' convention plugins necessary to build a Gradle plugin

src/main/descriptions/org.hiero.gradle.module.library.txt

@@ -0,0 +1 @@
+Convention plugin that applies the minimal of set 'org.hiero.gradle' convention plugins necessary to build a Java library module

src/main/descriptions/org.hiero.gradle.report.code-coverage.txt

@@ -0,0 +1 @@
+Conventions for 'jacoco-report-aggregation' to be used in a report aggregation project

src/main/descriptions/org.hiero.gradle.report.develocity.txt

@@ -0,0 +1 @@
+Conventions for 'com.gradle.develocity' that automatically accept the terms of use for 'scans.gradle.com' if users opt-in via '--scan'

src/main/descriptions/org.hiero.gradle.report.test-logger.txt

@@ -0,0 +1 @@
+Conventions for 'com.adarshr.test-logger' to improve test logging on the console

src/test/kotlin/org/hiero/gradle/test/ExampleTest.kt

@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: Apache-2.0
+package org.hiero.gradle.test
+
+import org.assertj.core.api.Assertions.assertThat
+import org.gradle.testkit.runner.TaskOutcome
+import org.hiero.gradle.test.fixtures.GradleProject
+import org.junit.jupiter.api.Test
+
+class ExampleTest {
+
+    @Test
+    fun `example project is working`() {
+        val p = GradleProject().copyFromFolder("example")
+
+        val result = p.qualityCheck()
+
+        assertThat(result.task(":module-app:qualityCheck")?.outcome).isEqualTo(TaskOutcome.SUCCESS)
+        assertThat(result.task(":module-lib:qualityCheck")?.outcome).isEqualTo(TaskOutcome.SUCCESS)
+    }
+}

src/test/kotlin/org/hiero/gradle/test/fixtures/GradleProject.kt

@@ -76,6 +76,12 @@ class GradleProject {
         return this
     }
 
+    fun copyFromFolder(folderName: String): GradleProject {
+        projectDir.deleteRecursively()
+        File(folderName).copyRecursively(projectDir)
+        return this
+    }
+
     fun settingsFile(content: String) = settingsFile.also { it.writeFormatted(content) }
 
     fun moduleBuildFile(content: String) = moduleBuildFile.also { it.writeFormatted(content) }