From 858440f684e8d62c3840f996f9a05f6e2d1b060f Mon Sep 17 00:00:00 2001
From: Jendrik Johannes <jendrik.johannes@gmail.com>
Date: Wed, 18 Dec 2024 08:21:18 +0100
Subject: [PATCH] chore: add documentation for users

Signed-off-by: Jendrik Johannes <jendrik.johannes@gmail.com>
---
 README.md                                     | 78 ++++++++++++++++++-
 ....hiero.gradle.feature.benchmark.gradle.kts |  5 +-
 2 files changed, 81 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 1cbf989..88eabce 100644
--- a/README.md
+++ b/README.md
@@ -90,6 +90,82 @@ Each plugin configures a certain build aspect, following this naming pattern:
 - `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.
 
+## Building a project that uses these plugins
+
+## From the command line
+
+Run `./gradlw` to get the list of tasks that are useful to check and test local changes:
+
+```
+Build tasks
+-----------
+assemble - Assembles the outputs of this project.
+build - Assembles and tests this project.
+qualityGate - Apply spotless rules and run all quality checks.
+test - Runs the test suite.
+```
+
+In addition, the following build parameters may be useful:
+
+|  Task  |               Parameter                |                          Description                           |                Remarks                 |
+|--------|----------------------------------------|----------------------------------------------------------------|----------------------------------------|
+| `test` | `-PactiveProcessorCount=<proc-number>` | not run tests in parallel and reduce number of processors used |                                        |
+| `jmh`  | `-PjmhTests=<includes>`                | select benchmarks to run - e.g. `com.example.jmh.Benchmark1`   | only projects with `feature.benchmark` |
+
+## In IntelliJ
+
+## In GitHub Actions
+
+GitHub action pipelines should use the following tasks and parameters.
+
+### Building and testing
+
+In a CI pipeline for PR validation with multiple steps use the following. (The available _test sets_ are determined by the additional `feature.test-*` plugins used in the project. )
+
+|       Task and Parameters       |         Description         |
+|---------------------------------|-----------------------------|
+| `./gradlew assemble --scan`     | Build all artifacts         |
+| `./gradlew qualityCheck --scan` | Run all checks except tests |
+| `./gradlew test --scan`         | Run all unit tests          |
+| `./gradlew <test-set> --scan`   | Run all tests in <test-set> |
+
+Alternatively, if you are fine to do all the above in one pipeline step, you can use:
+
+|      Task and Parameters      |             Description             |
+|-------------------------------|-------------------------------------|
+| `./gradlew build --scan`      | `assemble` + `qualiyCheck` + `test` |
+| `./gradlew <test-set> --scan` | Run all tests in <test-set>         |
+
+### Publishing
+
+Before doing the publishing, you may need to update the version (version.txt file) in a preceding step.
+
+|            Task and Parameters             |            Description             |
+|--------------------------------------------|------------------------------------|
+| `./gradlew --scn --no-configuration-cache` | Publish artifacts to Maven central |
+
+To perform the actual publishing:
+
+|             Task and Parameters             |            Description             |
+|---------------------------------------------|------------------------------------|
+| `./gradlew --scan --no-configuration-cache` | Publish artifacts to Maven central |
+
+The following parameters may be used to tune or test the publishing.
+
+`-PpublishingPackageGroup=<group-of-modules-to-publish>`
+`-Ps01SonatypeHost=<true|false>` (defaults to `false`)
+`-PpublishSigningEnabled=<true|false>` (defaults to `false`)
+`-PpublishTestRelease=<true|false>` (defaults to `false`)
+
+### Versioning
+
+`-PcommitPrefix=<prefix-before-commit-hash>` (defaults to `adhoc`)
+`-PnewVersion=<new-version>`
+
+### Testing Rust code on multiple operating systems
+
+`skipInstallRustToolchains`
+
 ## Contributing
 
 Whether you’re fixing bugs, enhancing features, or improving documentation, your contributions are important — let’s build something great together!
@@ -119,7 +195,7 @@ Your changes are automatically used when running a build.
 #### Add or adjust a test
 
 Each change done to the plugins should be covered by a test. The tests are located in
-[src/test/kotlin](src/main/kotlin). They are written in Kotlin using [JUnit5](https://junit.org/junit5/), 
+[src/test/kotlin](src/main/kotlin). They are written in Kotlin using [JUnit5](https://junit.org/junit5/),
 [AssertJ](https://assertj.github.io/doc/) and [Gradle Test Kit](https://docs.gradle.org/current/userguide/test_kit.html).
 Each test creates an artificial project that applies the plugin(s) under test, runs a build and asserts build results –
 such as: state of tasks executed, console logging, created files. Take a look at the existing tests for more details.
diff --git a/src/main/kotlin/org.hiero.gradle.feature.benchmark.gradle.kts b/src/main/kotlin/org.hiero.gradle.feature.benchmark.gradle.kts
index 4361107..b04f6ad 100644
--- a/src/main/kotlin/org.hiero.gradle.feature.benchmark.gradle.kts
+++ b/src/main/kotlin/org.hiero.gradle.feature.benchmark.gradle.kts
@@ -19,7 +19,10 @@ dependencies {
     jmhAnnotationProcessor("org.openjdk.jmh:jmh-generator-annprocess:${jmh.jmhVersion.get()}")
 }
 
-tasks.jmh { outputs.upToDateWhen { false } }
+tasks.jmh {
+    group = "build"
+    outputs.upToDateWhen { false }
+}
 
 tasks.withType<JMHTask>().configureEach {
     group = "jmh"