From 6311e90804fa416f275f376f568fa1dd07c9817d Mon Sep 17 00:00:00 2001 From: Jimisola Laursen Date: Sat, 7 Mar 2026 15:25:40 +0100 Subject: [PATCH 1/6] docs: documentation overhaul - Standardize README.md with consistent badges and structure - Add CONTRIBUTING.md with repo-specific dev setup - Add/update Antora docs structure - Remove per-repo GitHub Pages workflow - Point documentation badge to central site Signed-off-by: jimisola --- .github/workflows/publish_gh_pages.yml | 45 --------------------- CONTRIBUTING.md | 23 +++++++++++ README.adoc | 9 ----- README.md | 55 ++++++++++++++++++++++++++ docs/antora-playbook.yml | 1 + 5 files changed, 79 insertions(+), 54 deletions(-) delete mode 100644 .github/workflows/publish_gh_pages.yml create mode 100644 CONTRIBUTING.md delete mode 100644 README.adoc create mode 100644 README.md diff --git a/.github/workflows/publish_gh_pages.yml b/.github/workflows/publish_gh_pages.yml deleted file mode 100644 index 91cd42c..0000000 --- a/.github/workflows/publish_gh_pages.yml +++ /dev/null @@ -1,45 +0,0 @@ -name: Publish to GitHub Pages -on: - workflow_dispatch: - push: - branches: - - main - -concurrency: - group: github-pages - cancel-in-progress: false -# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages -permissions: - contents: read - pages: write - id-token: write -jobs: - publish_gh_pages: - runs-on: ubuntu-latest - environment: - name: github-pages - url: ${{ steps.deployment.outputs.page_url }} - steps: - - name: Checkout repository - uses: actions/checkout@v6 - - name: Configure Pages - uses: actions/configure-pages@v5 - - name: Install Node.js - uses: actions/setup-node@v6 - with: - node-version: "24" - - name: Install Antora - run: npm i antora - - name: Install Asciidoctor Kroki extension - run: npm i asciidoctor asciidoctor-kroki - - name: Create site folders - run: mkdir -p docs/build/site - - name: Generate Site - run: npx antora docs/antora-playbook.yml - - name: Upload Artifacts - uses: actions/upload-pages-artifact@v4 - with: - path: docs/build/site - - name: Deploy to GitHub Pages - id: deployment - uses: actions/deploy-pages@v4 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..c6a23e4 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,23 @@ +# Contributing to reqstool-java-gradle-plugin + +Thank you for your interest in contributing! + +For DCO sign-off, commit conventions, and code review process, see the organization-wide [CONTRIBUTING.md](https://github.com/reqstool/.github/blob/main/CONTRIBUTING.md). + +## Prerequisites + +- Java 17+ +- Gradle 9.3+ (use the wrapper) + +## Setup + +```bash +git clone https://github.com/reqstool/reqstool-java-gradle-plugin.git +cd reqstool-java-gradle-plugin +``` + +## Build & Test + +```bash +./gradlew build +``` diff --git a/README.adoc b/README.adoc deleted file mode 100644 index 67f8c08..0000000 --- a/README.adoc +++ /dev/null @@ -1,9 +0,0 @@ -image:https://img.shields.io/github/commit-activity/m/reqstool/reqstool-java-gradle-plugin?label=commits&style=for-the-badge["Commit Activity", link="https://github.com/reqstool/reqstool-java-gradle-plugin/pulse"] -image:https://img.shields.io/github/issues/reqstool/reqstool-java-gradle-plugin?style=for-the-badge&logo=github["GitHub Issues", link="https://github.com/reqstool/reqstool-java-gradle-plugin/issues"] -image:https://img.shields.io/badge/Java-17-brightgreen.svg?style=for-the-badge["JVM support", link="https://sdkman.io"] -image:https://img.shields.io/github/license/reqstool/reqstool-java-gradle-plugin?style=for-the-badge&logo=opensourceinitiative["License", link="https://opensource.org/license/mit/"] -image:https://img.shields.io/github/actions/workflow/status/reqstool/reqstool-java-gradle-plugin/build.yml?style=for-the-badge&logo=github["Build", link="https://github.com/reqstool/reqstool-java-gradle-plugin/actions/workflows/build.yml"] -image:https://img.shields.io/badge/Documentation-blue?style=for-the-badge&link=docs["Static Badge", link="https://reqstool.github.io/reqstool-java-gradle-plugin/"] - -See: -link:https://github.com/reqstool/reqstool-java-gradle-plugin/blob/main/docs/modules/ROOT/pages/index.adoc[Documentation] diff --git a/README.md b/README.md new file mode 100644 index 0000000..130f269 --- /dev/null +++ b/README.md @@ -0,0 +1,55 @@ +[![Commit Activity](https://img.shields.io/github/commit-activity/m/reqstool/reqstool-java-gradle-plugin?label=commits&style=for-the-badge)](https://github.com/reqstool/reqstool-java-gradle-plugin/pulse) +[![GitHub Issues](https://img.shields.io/github/issues/reqstool/reqstool-java-gradle-plugin?style=for-the-badge&logo=github)](https://github.com/reqstool/reqstool-java-gradle-plugin/issues) +[![License](https://img.shields.io/github/license/reqstool/reqstool-java-gradle-plugin?style=for-the-badge&logo=opensourceinitiative)](https://opensource.org/license/mit/) +[![Build](https://img.shields.io/github/actions/workflow/status/reqstool/reqstool-java-gradle-plugin/build.yml?style=for-the-badge&logo=github)](https://github.com/reqstool/reqstool-java-gradle-plugin/actions/workflows/build.yml) +[![Documentation](https://img.shields.io/badge/Documentation-blue?style=for-the-badge&link=docs)](https://reqstool.github.io) + +# Reqstool Gradle Plugin + +Gradle build plugin for [reqstool](https://github.com/reqstool/reqstool-client) that assembles requirements traceability artifacts. + +## Overview + +Collects `@Requirements` and `@SVCs` annotations from compiled Java code, combines them with test results, and packages everything into a ZIP artifact for analysis by the reqstool CLI. Supports Java 17+. + +## Installation + +Add the plugin to your `build.gradle`: + +```groovy +plugins { + id 'io.github.reqstool.gradle-plugin' version '0.1.0' +} + +requirementsTool { + datasetPath = file('docs/reqstool') +} + +tasks.named('build') { + finalizedBy tasks.named('assembleRequirements') +} + +tasks.named('assembleRequirements') { + dependsOn tasks.named('test') +} +``` + +## Usage + +```bash +gradle clean build +``` + +The plugin generates a ZIP artifact in `build/reqstool/` containing requirements, annotations, and test results. + +## Documentation + +Full documentation can be found [here](https://reqstool.github.io). + +## Contributing + +See the organization-wide [CONTRIBUTING.md](https://github.com/reqstool/.github/blob/main/CONTRIBUTING.md). + +## License + +MIT License. diff --git a/docs/antora-playbook.yml b/docs/antora-playbook.yml index dfd193d..17dc05a 100644 --- a/docs/antora-playbook.yml +++ b/docs/antora-playbook.yml @@ -1,4 +1,5 @@ # yaml-language-server: $schema=https://raw.githubusercontent.com/asciidoctor/asciidoctor-intellij-plugin/main/src/main/resources/jsonSchemas/antoraPlaybookSchema.json +# For local development only. Published site: https://reqstool.github.io site: title: Reqstool Gradle Plugin From 3405e2fcce508ffdb0d5b7d35ebb1b281b792551 Mon Sep 17 00:00:00 2001 From: Jimisola Laursen Date: Sat, 7 Mar 2026 16:19:01 +0100 Subject: [PATCH 2/6] docs: rename Requirements to Prerequisites Signed-off-by: jimisola --- docs/modules/ROOT/pages/description.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/modules/ROOT/pages/description.adoc b/docs/modules/ROOT/pages/description.adoc index 03442f5..0525745 100644 --- a/docs/modules/ROOT/pages/description.adoc +++ b/docs/modules/ROOT/pages/description.adoc @@ -51,7 +51,7 @@ my-project/ Run `gradle build` and the ZIP artifact will be created automatically. -=== Requirements +=== Prerequisites * Gradle 9.0+ * Java 17+ From db78079f75a95874f6fa3b6be75d697ce93b7961 Mon Sep 17 00:00:00 2001 From: Jimisola Laursen Date: Sat, 7 Mar 2026 16:27:55 +0100 Subject: [PATCH 3/6] docs: simplify license page to uniform format Signed-off-by: jimisola --- docs/modules/ROOT/pages/license.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/modules/ROOT/pages/license.adoc b/docs/modules/ROOT/pages/license.adoc index f673488..0277da8 100644 --- a/docs/modules/ROOT/pages/license.adoc +++ b/docs/modules/ROOT/pages/license.adoc @@ -1,3 +1,3 @@ == License -This project is licensed under the MIT License. +MIT License. From 8be0da7cd3ad6b92bef28252e6f8f2cccd62abba Mon Sep 17 00:00:00 2001 From: Jimisola Laursen Date: Sat, 7 Mar 2026 16:42:12 +0100 Subject: [PATCH 4/6] docs: streamline nav and page structure - Separate nav items instead of single include-based page - Merge description.adoc content into index.adoc - Remove license.adoc, add inline license to index.adoc - Change nav label from Start to Overview Signed-off-by: jimisola --- docs/modules/ROOT/nav.adoc | 4 +- docs/modules/ROOT/pages/description.adoc | 58 ---------------------- docs/modules/ROOT/pages/index.adoc | 61 ++++++++++++++++++++++-- docs/modules/ROOT/pages/license.adoc | 3 -- 4 files changed, 60 insertions(+), 66 deletions(-) delete mode 100644 docs/modules/ROOT/pages/description.adoc delete mode 100644 docs/modules/ROOT/pages/license.adoc diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index 7917907..cfb3122 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/docs/modules/ROOT/nav.adoc @@ -1 +1,3 @@ -* xref:index.adoc[Start] +* xref:index.adoc[Overview] +* xref:configuration.adoc[Configuration] +* xref:usage.adoc[Usage] diff --git a/docs/modules/ROOT/pages/description.adoc b/docs/modules/ROOT/pages/description.adoc deleted file mode 100644 index 0525745..0000000 --- a/docs/modules/ROOT/pages/description.adoc +++ /dev/null @@ -1,58 +0,0 @@ -== Description - -This Gradle plugin generates a ZIP artifact containing combined annotations and various reports for Reqstool. It provides zero-configuration defaults while allowing customization when needed. - -=== Features - -* *Zero-configuration*: Works out of the box with sensible defaults -* *Automatic lifecycle integration*: Runs as part of the standard `build` task -* *Maven publishing support*: Automatically registers ZIP artifact for publication -* *Combines annotations*: Merges requirements annotations from implementation and test code -* *Assembles ZIP artifact*: Creates structured ZIP containing requirements, test results, and configuration - -=== Quick Start - -==== Apply the Plugin - -[source,gradle] ----- -plugins { - id 'io.github.reqstool.gradle-plugin' version '0.1.0' -} ----- - -==== Default Behavior - -The plugin automatically: - -1. Runs after the `check` task (when tests complete) -2. Combines annotation files from `build/generated-sources/` and `build/generated-test-sources/` -3. Creates a ZIP artifact in `build/reqstool/` containing: - * `requirements.yml` (from `./reqstool/` directory) - * `software_verification_cases.yml` (optional) - * `manual_verification_results.yml` (optional) - * `annotations.yml` (combined/merged annotations) - * `test_results/` (XML test results from `build/test-results/`) - * `reqstool_config.yml` (configuration manifest) -4. Registers the ZIP for Maven publication (if `maven-publish` plugin is applied) - -==== Minimal Setup - -Create a `reqstool/` directory in your project root with a `requirements.yml` file: - -[source] ----- -my-project/ -├── build.gradle -├── reqstool/ -│ └── requirements.yml (mandatory) -└── src/ ----- - -Run `gradle build` and the ZIP artifact will be created automatically. - -=== Prerequisites - -* Gradle 9.0+ -* Java 17+ -* A `requirements.yml` file in the dataset directory (default: `./reqstool/`) diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc index b96830b..ddd39c6 100644 --- a/docs/modules/ROOT/pages/index.adoc +++ b/docs/modules/ROOT/pages/index.adoc @@ -1,9 +1,62 @@ = Reqstool Gradle Plugin -include::description.adoc[] +This Gradle plugin generates a ZIP artifact containing combined annotations and various reports for Reqstool. It provides zero-configuration defaults while allowing customization when needed. -include::configuration.adoc[] +=== Features -include::usage.adoc[] +* *Zero-configuration*: Works out of the box with sensible defaults +* *Automatic lifecycle integration*: Runs as part of the standard `build` task +* *Maven publishing support*: Automatically registers ZIP artifact for publication +* *Combines annotations*: Merges requirements annotations from implementation and test code +* *Assembles ZIP artifact*: Creates structured ZIP containing requirements, test results, and configuration -include::license.adoc[] +=== Quick Start + +==== Apply the Plugin + +[source,gradle] +---- +plugins { + id 'io.github.reqstool.gradle-plugin' version '0.1.0' +} +---- + +==== Default Behavior + +The plugin automatically: + +1. Runs after the `check` task (when tests complete) +2. Combines annotation files from `build/generated-sources/` and `build/generated-test-sources/` +3. Creates a ZIP artifact in `build/reqstool/` containing: + * `requirements.yml` (from `./reqstool/` directory) + * `software_verification_cases.yml` (optional) + * `manual_verification_results.yml` (optional) + * `annotations.yml` (combined/merged annotations) + * `test_results/` (XML test results from `build/test-results/`) + * `reqstool_config.yml` (configuration manifest) +4. Registers the ZIP for Maven publication (if `maven-publish` plugin is applied) + +==== Minimal Setup + +Create a `reqstool/` directory in your project root with a `requirements.yml` file: + +[source] +---- +my-project/ +├── build.gradle +├── reqstool/ +│ └── requirements.yml (mandatory) +└── src/ +---- + +Run `gradle build` and the ZIP artifact will be created automatically. + +=== Prerequisites + +* Gradle 9.0+ +* Java 17+ +* A `requirements.yml` file in the dataset directory (default: `./reqstool/`) + +== License + +MIT License. diff --git a/docs/modules/ROOT/pages/license.adoc b/docs/modules/ROOT/pages/license.adoc deleted file mode 100644 index 0277da8..0000000 --- a/docs/modules/ROOT/pages/license.adoc +++ /dev/null @@ -1,3 +0,0 @@ -== License - -MIT License. From a485c44193406756f23300d69b333132ebeed0a8 Mon Sep 17 00:00:00 2001 From: Jimisola Laursen Date: Sat, 7 Mar 2026 18:43:12 +0100 Subject: [PATCH 5/6] docs: use lowercase reqstool consistently Signed-off-by: jimisola --- docs/modules/ROOT/pages/index.adoc | 16 ++++++++-------- docs/modules/ROOT/pages/usage.adoc | 2 +- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc index ddd39c6..dfb65e0 100644 --- a/docs/modules/ROOT/pages/index.adoc +++ b/docs/modules/ROOT/pages/index.adoc @@ -1,8 +1,8 @@ -= Reqstool Gradle Plugin += reqstool Gradle Plugin -This Gradle plugin generates a ZIP artifact containing combined annotations and various reports for Reqstool. It provides zero-configuration defaults while allowing customization when needed. +This Gradle plugin generates a ZIP artifact containing combined annotations and various reports for reqstool. It provides zero-configuration defaults while allowing customization when needed. -=== Features +== Features * *Zero-configuration*: Works out of the box with sensible defaults * *Automatic lifecycle integration*: Runs as part of the standard `build` task @@ -10,9 +10,9 @@ This Gradle plugin generates a ZIP artifact containing combined annotations and * *Combines annotations*: Merges requirements annotations from implementation and test code * *Assembles ZIP artifact*: Creates structured ZIP containing requirements, test results, and configuration -=== Quick Start +== Quick Start -==== Apply the Plugin +== Apply the Plugin [source,gradle] ---- @@ -21,7 +21,7 @@ plugins { } ---- -==== Default Behavior +== Default Behavior The plugin automatically: @@ -36,7 +36,7 @@ The plugin automatically: * `reqstool_config.yml` (configuration manifest) 4. Registers the ZIP for Maven publication (if `maven-publish` plugin is applied) -==== Minimal Setup +== Minimal Setup Create a `reqstool/` directory in your project root with a `requirements.yml` file: @@ -51,7 +51,7 @@ my-project/ Run `gradle build` and the ZIP artifact will be created automatically. -=== Prerequisites +== Prerequisites * Gradle 9.0+ * Java 17+ diff --git a/docs/modules/ROOT/pages/usage.adoc b/docs/modules/ROOT/pages/usage.adoc index da6dbb6..e4998bb 100644 --- a/docs/modules/ROOT/pages/usage.adoc +++ b/docs/modules/ROOT/pages/usage.adoc @@ -1,6 +1,6 @@ == Usage -To use the Reqstool Gradle Plugin, add the following configuration to your Gradle project's `build.gradle`: +To use the reqstool Gradle Plugin, add the following configuration to your Gradle project's `build.gradle`: === Basic Usage From 29d9cd81c788949c256ca55ee9bb308c1029354f Mon Sep 17 00:00:00 2001 From: Jimisola Laursen Date: Sat, 7 Mar 2026 19:34:19 +0100 Subject: [PATCH 6/6] docs: update Java prerequisite from 17+ to 21+ Signed-off-by: jimisola --- CONTRIBUTING.md | 2 +- README.md | 2 +- docs/modules/ROOT/pages/index.adoc | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c6a23e4..075b1f7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,7 +6,7 @@ For DCO sign-off, commit conventions, and code review process, see the organizat ## Prerequisites -- Java 17+ +- Java 21+ - Gradle 9.3+ (use the wrapper) ## Setup diff --git a/README.md b/README.md index 130f269..9ce1db4 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ Gradle build plugin for [reqstool](https://github.com/reqstool/reqstool-client) ## Overview -Collects `@Requirements` and `@SVCs` annotations from compiled Java code, combines them with test results, and packages everything into a ZIP artifact for analysis by the reqstool CLI. Supports Java 17+. +Collects `@Requirements` and `@SVCs` annotations from compiled Java code, combines them with test results, and packages everything into a ZIP artifact for analysis by the reqstool CLI. Supports Java 21+. ## Installation diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc index dfb65e0..09711a6 100644 --- a/docs/modules/ROOT/pages/index.adoc +++ b/docs/modules/ROOT/pages/index.adoc @@ -54,7 +54,7 @@ Run `gradle build` and the ZIP artifact will be created automatically. == Prerequisites * Gradle 9.0+ -* Java 17+ +* Java 21+ * A `requirements.yml` file in the dataset directory (default: `./reqstool/`) == License