diff --git a/.github/workflows/publish_gh_pages.yml b/.github/workflows/publish_gh_pages.yml deleted file mode 100644 index 11a457d..0000000 --- a/.github/workflows/publish_gh_pages.yml +++ /dev/null @@ -1,47 +0,0 @@ -name: Publish to GitHub Pages -on: - workflow_dispatch: - release: - types: [created] - 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: Generate Site - run: npx antora docs/antora-playbook.yml - - name: Create site folders - run: mkdir -p docs/build/site - - 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..d5ecba2 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,23 @@ +# Contributing to reqstool-java-maven-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 21+ +- Maven 3.9+ + +## Setup + +```bash +git clone https://github.com/reqstool/reqstool-java-maven-plugin.git +cd reqstool-java-maven-plugin +``` + +## Build & Test + +```bash +mvn verify +``` diff --git a/README.adoc b/README.adoc deleted file mode 100644 index 5d99c57..0000000 --- a/README.adoc +++ /dev/null @@ -1,9 +0,0 @@ - -image:https://img.shields.io/github/commit-activity/m/reqstool/reqstool-java-maven-plugin?label=commits&style=for-the-badge["Commit Activity", link="https://github.com/reqstool/reqstool-java-maven-plugin/pulse"] -image:https://img.shields.io/github/issues/reqstool/reqstool-java-maven-plugin?style=for-the-badge&logo=github["GitHub Issues", link="https://github.com/reqstool/reqstool-java-maven-plugin/issues"] -image:https://img.shields.io/badge/Java-21-brightgreen.svg?style=for-the-badge["JVM support", link="https://sdkman.io"] -image:https://img.shields.io/github/license/reqstool/reqstool-java-maven-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-maven-plugin/build.yml?style=for-the-badge&logo=github["Build", link="https://github.com/reqstool/reqstool-java-maven-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-maven-plugin/"] - -include::docs/modules/ROOT/pages/index.adoc[] diff --git a/README.md b/README.md new file mode 100644 index 0000000..94db33f --- /dev/null +++ b/README.md @@ -0,0 +1,55 @@ +[![Commit Activity](https://img.shields.io/github/commit-activity/m/reqstool/reqstool-java-maven-plugin?label=commits&style=for-the-badge)](https://github.com/reqstool/reqstool-java-maven-plugin/pulse) +[![GitHub Issues](https://img.shields.io/github/issues/reqstool/reqstool-java-maven-plugin?style=for-the-badge&logo=github)](https://github.com/reqstool/reqstool-java-maven-plugin/issues) +[![License](https://img.shields.io/github/license/reqstool/reqstool-java-maven-plugin?style=for-the-badge&logo=opensourceinitiative)](https://opensource.org/license/mit/) +[![Build](https://img.shields.io/github/actions/workflow/status/reqstool/reqstool-java-maven-plugin/build.yml?style=for-the-badge&logo=github)](https://github.com/reqstool/reqstool-java-maven-plugin/actions/workflows/build.yml) +[![Documentation](https://img.shields.io/badge/Documentation-blue?style=for-the-badge&link=docs)](https://reqstool.github.io) + +# Reqstool Maven Plugin + +Maven 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. + +## Installation + +Add the plugin to your `pom.xml`: + +```xml + + io.github.reqstool + reqstool-maven-plugin + 1.0.4 + + + + assemble-and-attach-zip-artifact + + + + + ${project.basedir}/docs/reqstool + + +``` + +## Usage + +```bash +mvn clean verify +``` + +The plugin generates a ZIP artifact in `target/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 725bdce..caf18b6 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 Maven Plugin diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index 76986d1..cfb3122 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/docs/modules/ROOT/nav.adoc @@ -1 +1,3 @@ -* xref:index.adoc[Start] \ No newline at end of file +* xref:index.adoc[Overview] +* xref:configuration.adoc[Configuration] +* xref:usage.adoc[Usage] diff --git a/docs/modules/ROOT/pages/configuration.adoc b/docs/modules/ROOT/pages/configuration.adoc index cf0f73a..839b43b 100644 --- a/docs/modules/ROOT/pages/configuration.adoc +++ b/docs/modules/ROOT/pages/configuration.adoc @@ -1,194 +1,141 @@ == Configuration -To configure the plugin add a `` block for the plugin under the `` in pom.xml. - -== Complete Configuration Example - -```xml - - - - io.github.reqstool - reqstool-maven-plugin - 1.0.4 - - - - ${project.build.directory}/generated-sources/annotations/resources/annotations.yml - - - ${project.build.directory}/generated-test-sources/test-annotations/resources/annotations.yml - - - ${project.build.directory}/reqstool - - ${project.basedir}/reqstool - - - - target/surefire-reports/**/*.xml - target/failsafe-reports/**/*.xml - - - - ${project} - ${log} - - - false - false - false - - - - -``` - -== Configuration Parameters - -=== requirementsAnnotationsFile +The plugin provides sensible defaults, but you can customize if needed by adding a `` block in your `pom.xml`: -The `requirementsAnnotationsFile` parameter specifies the path to the requirements annotations file. -Defaults to the value set below. +=== Complete Configuration Example -```xml +[source,xml] +---- + + ${project.build.directory}/generated-sources/annotations/resources/annotations.yml - -``` - -=== svcsAnnotationsFile - -The `svcsAnnotationsFile` parameter specifies the path to the svcs annotations file. -Defaults to the value set below. - -```xml - + + ${project.build.directory}/generated-test-sources/test-annotations/resources/annotations.yml - -``` + + + ${project.build.directory}/reqstool -=== outputDirectory + + + ${project.basedir}/reqstool -The `outputDirectory` parameter specifies the path to where to put the generated output. -Defaults to the value set below. - -```xml - - - ${project.build.directory}/reqstool - - - -``` + + + target/surefire-reports/**/*.xml + target/failsafe-reports/**/*.xml + -=== datasetPath + + false -The `datasetPath` parameter specifies the path to the dataset. -Defaults to the value set below. + + false -```xml - - - ${project.basedir}/reqstool - + + false +---- -``` +=== Configuration Parameters -=== project +==== requirementsAnnotationsFile -The `project` parameter specifies the name of the maven project. +The `requirementsAnnotationsFile` parameter specifies the path to the requirements annotations file. Defaults to the value set below. -```xml - - - ${project} - - +[source,xml] +---- + + ${project.build.directory}/generated-sources/annotations/resources/annotations.yml + +---- -``` +==== svcsAnnotationsFile -=== testResults +The `svcsAnnotationsFile` parameter specifies the path to the SVCS (Software Verification Cases) annotations file. +Defaults to the value set below. -The `testResults` parameter specifies one or more testResult paths. +[source,xml] +---- + + ${project.build.directory}/generated-test-sources/test-annotations/resources/annotations.yml + +---- -```xml - - - path/to/test/result.xml - path/to/test/result.xml - - +==== outputDirectory -``` +The `outputDirectory` parameter specifies the path to where to put the generated output. +Defaults to the value set below. -=== log +[source,xml] +---- +${project.build.directory}/reqstool +---- -The `log` parameter specifies the log. -Defaults to the value set below. +==== datasetPath -```xml - - - ${log} - - +The `datasetPath` parameter specifies the path to the dataset directory containing `requirements.yml` and optional files. +Defaults to the value set below. -``` +[source,xml] +---- +${project.basedir}/reqstool +---- -=== skip +==== testResults -Skip the execution of the plugin. -Defaults to the value set below. +The `testResults` parameter specifies one or more test result file patterns. +Supports Ant-style pattern matching. -```xml - - - false - - +[source,xml] +---- + + target/surefire-reports/**/*.xml + target/failsafe-reports/**/*.xml + +---- -``` +==== skip -=== skipAssembleZipArtifact +Skip the execution of the entire plugin. +Defaults to `false`. -Skip zip artifact assembly. -Defaults to the value set below. +[source,xml] +---- +false +---- -```xml - - - false - - +==== skipAssembleZipArtifact -``` +Skip ZIP artifact assembly but continue with annotation combining. +Defaults to `false`. -=== skipAttachZipArtifact +[source,xml] +---- +false +---- -Skip zip artifact attachment. -Defaults to the value set below. +==== skipAttachZipArtifact -```xml - - - false - - +Skip artifact attachment for deployment. +Defaults to `false`. -``` +[source,xml] +---- +false +---- -Notes: +=== Notes * All path parameters support both absolute and relative paths * Maven property placeholders (`${...}`) can be used in all configuration values * The plugin executes in the `verify` phase by default -* Test result paths support Ant-style pattern matching \ No newline at end of file +* Test result paths support Ant-style pattern matching diff --git a/docs/modules/ROOT/pages/description.adoc b/docs/modules/ROOT/pages/description.adoc deleted file mode 100644 index 0e703f6..0000000 --- a/docs/modules/ROOT/pages/description.adoc +++ /dev/null @@ -1,3 +0,0 @@ -== Description - -This Maven plugin generates a zip artifact containing combined annotations and various reports for Reqstool. \ No newline at end of file diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc index bf27b0a..a44f5eb 100644 --- a/docs/modules/ROOT/pages/index.adoc +++ b/docs/modules/ROOT/pages/index.adoc @@ -1,9 +1,75 @@ -= Reqstool Maven Plugin += reqstool Maven Plugin -include::description.adoc[] +This Maven plugin generates a ZIP artifact containing combined annotations and various reports for reqstool. It provides sensible defaults while allowing full customization. -include::configuration.adoc[] +== Features -include::usage.adoc[] +* *Sensible defaults*: Works out of the box with standard Maven project layouts +* *Automatic lifecycle integration*: Runs in the `verify` phase to ensure tests complete first +* *Maven repository publishing*: ZIP artifact is attached for deployment to Maven repositories +* *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[] \ No newline at end of file +== Quick Start + +== Add the Plugin + +[source,xml] +---- + + + + io.github.reqstool + reqstool-maven-plugin + 1.0.4 + + + + assemble-and-attach-zip-artifact + + + + + + +---- + +== Default Behavior + +The plugin automatically: + +1. Runs during the `verify` phase (after all tests complete) +2. Combines annotation files from `target/generated-sources/` and `target/generated-test-sources/` +3. Creates a ZIP artifact in `target/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 Surefire and Failsafe) + * `reqstool_config.yml` (configuration manifest) +4. Attaches the ZIP for deployment to Maven repositories + +== Minimal Setup + +Create a `reqstool/` directory in your project root with a `requirements.yml` file: + +[source] +---- +my-project/ +├── pom.xml +├── reqstool/ +│ └── requirements.yml (mandatory) +└── src/ +---- + +Run `mvn verify` and the ZIP artifact will be created automatically. + +== Prerequisites + +* Maven 3.9+ +* Java 21+ +* 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 f673488..0000000 --- a/docs/modules/ROOT/pages/license.adoc +++ /dev/null @@ -1,3 +0,0 @@ -== License - -This project is licensed under the MIT License. diff --git a/docs/modules/ROOT/pages/usage.adoc b/docs/modules/ROOT/pages/usage.adoc index 719d2d1..45fb5d6 100644 --- a/docs/modules/ROOT/pages/usage.adoc +++ b/docs/modules/ROOT/pages/usage.adoc @@ -1,8 +1,11 @@ == Usage -To use the Reqstool Java Maven Plugin, add the following configuration to your Maven project's `pom.xml`: +To use the reqstool Maven Plugin, add the following configuration to your Maven project's `pom.xml`: -```xml +=== Basic Usage + +[source,xml] +---- @@ -16,19 +19,56 @@ To use the Reqstool Java Maven Plugin, add the following configuration to your M - - - io.github.reqstool - reqstool-java-annotations - 1.0.4 - - -``` +---- + +The plugin will automatically integrate with the standard Maven build lifecycle. + +=== Annotation Dependency + +To use `@Requirements` and `@SVCs` annotations in your code, add the annotations dependency: + +[source,xml] +---- + + + io.github.reqstool + reqstool-java-annotations + 1.0.4 + + +---- + +=== Running Manually + +The goal can be invoked manually: + +[source,bash] +---- +mvn reqstool:assemble-and-attach-zip-artifact +---- + +=== Available Goals + +==== assemble-and-attach-zip-artifact + +Main goal that: + +* Bound to the `verify` phase (ensures tests have run) +* Combines annotation files +* Assembles ZIP artifact +* Attaches artifact for deployment -The default `` the plugin runs during is `verify`, this is done to ensure all test files are generated before the plugin runs. +=== Default Lifecycle +The plugin automatically integrates into the standard Maven build: +1. Plugin is configured with an execution binding +2. The `assemble-and-attach-zip-artifact` goal runs during `verify` phase +3. Goal runs after all tests complete (Surefire and Failsafe) +4. ZIP artifact is created in `target/reqstool/` +5. Artifact is attached for deployment to Maven repositories +The ZIP artifact will be published with classifier `reqstool` (e.g., `my-app-1.0.0-reqstool.zip`).