diff --git a/README.md b/README.md index 94db33f..c4bcb11 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,8 @@ Maven build plugin for [reqstool](https://github.com/reqstool/reqstool-client) t 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. +The plugin binds to the `verify` lifecycle phase and runs automatically after tests complete. No additional lifecycle configuration is needed in most projects. + ## Installation Add the plugin to your `pom.xml`: @@ -34,6 +36,83 @@ Add the plugin to your `pom.xml`: ``` +## Configuration + +All parameters are optional. Defaults match the standard Maven project layout. + +| Parameter | Type | Default | Description | +|---|---|---|---| +| `requirementsAnnotationsFile` | `File` | `${project.build.directory}/generated-sources/annotations/resources/annotations.yml` | Requirements annotations YAML file generated by the annotation processor for the main source set | +| `svcsAnnotationsFile` | `File` | `${project.build.directory}/generated-test-sources/test-annotations/resources/annotations.yml` | SVCs annotations YAML file generated by the annotation processor for the test source set | +| `outputDirectory` | `File` | `${project.build.directory}/reqstool` | Output directory for the ZIP artifact and combined annotations file | +| `datasetPath` | `File` | `${project.basedir}/reqstool` | Directory containing `requirements.yml` and optional supporting files | +| `testResults` | `String[]` | _(none)_ | Ant-style glob patterns for test result XML files to include in the ZIP | +| `skip` | `boolean` | `false` | Skip all plugin execution | +| `skipAssembleZipArtifact` | `boolean` | `false` | Skip ZIP assembly; annotations are still combined into `annotations.yml` | +| `skipAttachZipArtifact` | `boolean` | `false` | Skip attaching the ZIP artifact to the Maven project | + +### Dataset directory + +The `datasetPath` directory must contain at minimum a `requirements.yml` file. Optional files in the same directory are included if present: + +| File | Required | +|---|---| +| `requirements.yml` | Yes | +| `software_verification_cases.yml` | No | +| `manual_verification_results.yml` | No | + +### Full configuration example + +```xml + + io.github.reqstool + reqstool-maven-plugin + 1.0.4 + + + + assemble-and-attach-zip-artifact + + + + + + ${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}/docs/reqstool + + target/surefire-reports/**/*.xml + target/failsafe-reports/**/*.xml + + false + false + false + + +``` + +### Command-line overrides + +All parameters can be overridden on the command line using the `reqstool.` prefix: + +```bash +mvn verify -Dreqstool.skip=true +mvn verify -Dreqstool.datasetPath=/custom/path +mvn verify -Dreqstool.skipAssembleZipArtifact=true +``` + +## Goal reference + +### `assemble-and-attach-zip-artifact` + +Default phase: `verify` + +Combines requirements and SVCs annotations, writes a merged `annotations.yml` to `outputDirectory`, and (unless `skipAssembleZipArtifact` is set) assembles a ZIP artifact at `/-reqstool.zip`. The ZIP is attached to the Maven project with classifier `reqstool` and extension `zip`. + ## Usage ```bash diff --git a/docs/modules/ROOT/pages/configuration.adoc b/docs/modules/ROOT/pages/configuration.adoc index 839b43b..e3e8be2 100644 --- a/docs/modules/ROOT/pages/configuration.adoc +++ b/docs/modules/ROOT/pages/configuration.adoc @@ -1,141 +1,115 @@ -== Configuration += Configuration -The plugin provides sensible defaults, but you can customize if needed by adding a `` block in your `pom.xml`: +The plugin provides sensible defaults that match the standard Maven project layout. +Override only what you need by adding a `` block in your `pom.xml`. -=== Complete Configuration Example +== Configuration reference -[source,xml] ----- - - - - - ${project.build.directory}/generated-sources/annotations/resources/annotations.yml - +[cols="1,1,2,2",options="header"] +|=== +|Parameter |Type |Default |Description - - - - ${project.build.directory}/generated-test-sources/test-annotations/resources/annotations.yml - +|`requirementsAnnotationsFile` +|`File` +|`${project.build.directory}/generated-sources/annotations/resources/annotations.yml` +|Requirements annotations YAML file generated by the annotation processor for the main source set - - - ${project.build.directory}/reqstool +|`svcsAnnotationsFile` +|`File` +|`${project.build.directory}/generated-test-sources/test-annotations/resources/annotations.yml` +|SVCs annotations YAML file generated by the annotation processor for the test source set - - - ${project.basedir}/reqstool +|`outputDirectory` +|`File` +|`${project.build.directory}/reqstool` +|Output directory for the ZIP artifact and combined `annotations.yml` - - - target/surefire-reports/**/*.xml - target/failsafe-reports/**/*.xml - +|`datasetPath` +|`File` +|`${project.basedir}/reqstool` +|Directory containing `requirements.yml` and optional supporting files - - false +|`testResults` +|`String[]` +|_(none)_ +|Ant-style glob patterns for test result XML files to include in the ZIP - - false +|`skip` +|`boolean` +|`false` +|Skip all plugin execution - - false - ----- - -=== Configuration Parameters - -==== requirementsAnnotationsFile +|`skipAssembleZipArtifact` +|`boolean` +|`false` +|Skip ZIP assembly; annotations are still combined into `annotations.yml` -The `requirementsAnnotationsFile` parameter specifies the path to the requirements annotations file. -Defaults to the value set below. - -[source,xml] ----- - - ${project.build.directory}/generated-sources/annotations/resources/annotations.yml - ----- +|`skipAttachZipArtifact` +|`boolean` +|`false` +|Skip attaching the ZIP artifact to the Maven project +|=== -==== svcsAnnotationsFile +== Dataset directory -The `svcsAnnotationsFile` parameter specifies the path to the SVCS (Software Verification Cases) annotations file. -Defaults to the value set below. +The `datasetPath` directory must contain at minimum a `requirements.yml` file. +Optional files in the same directory are included if present. -[source,xml] ----- - - ${project.build.directory}/generated-test-sources/test-annotations/resources/annotations.yml - ----- +[cols="1,1",options="header"] +|=== +|File |Required -==== outputDirectory +|`requirements.yml` +|Yes -The `outputDirectory` parameter specifies the path to where to put the generated output. -Defaults to the value set below. +|`software_verification_cases.yml` +|No -[source,xml] ----- -${project.build.directory}/reqstool ----- +|`manual_verification_results.yml` +|No +|=== -==== datasetPath +== Minimal configuration -The `datasetPath` parameter specifies the path to the dataset directory containing `requirements.yml` and optional files. -Defaults to the value set below. +Only `datasetPath` needs to be set when the dataset lives outside the default `reqstool/` directory: [source,xml] ---- -${project.basedir}/reqstool ----- - -==== testResults - -The `testResults` parameter specifies one or more test result file patterns. -Supports Ant-style pattern matching. - -[source,xml] ----- - - target/surefire-reports/**/*.xml - target/failsafe-reports/**/*.xml - ----- - -==== skip - -Skip the execution of the entire plugin. -Defaults to `false`. - -[source,xml] ----- -false + + ${project.basedir}/docs/reqstool + ---- -==== skipAssembleZipArtifact - -Skip ZIP artifact assembly but continue with annotation combining. -Defaults to `false`. +== Complete configuration example [source,xml] ---- -false + + + ${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}/docs/reqstool + + target/surefire-reports/**/*.xml + target/failsafe-reports/**/*.xml + + false + false + false + ---- -==== skipAttachZipArtifact +== Command-line overrides -Skip artifact attachment for deployment. -Defaults to `false`. +All parameters can be overridden on the command line using the `reqstool.` prefix: -[source,xml] +[source,bash] ---- -false +mvn verify -Dreqstool.skip=true +mvn verify -Dreqstool.datasetPath=/custom/path +mvn verify -Dreqstool.skipAssembleZipArtifact=true ---- - -=== 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 diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc index a44f5eb..bd7e4b0 100644 --- a/docs/modules/ROOT/pages/index.adoc +++ b/docs/modules/ROOT/pages/index.adoc @@ -12,7 +12,7 @@ This Maven plugin generates a ZIP artifact containing combined annotations and v == Quick Start -== Add the Plugin +=== Add the plugin [source,xml] ---- @@ -29,35 +29,38 @@ This Maven plugin generates a ZIP artifact containing combined annotations and v + + ${project.basedir}/docs/reqstool + ---- -== Default Behavior +=== 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) + * `requirements.yml` (from `datasetPath` 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) + * `annotations.yml` (combined annotations) + * `test_results/` (XML test results matching `testResults` patterns) * `reqstool_config.yml` (configuration manifest) 4. Attaches the ZIP for deployment to Maven repositories -== Minimal Setup +=== Minimal setup -Create a `reqstool/` directory in your project root with a `requirements.yml` file: +Create a dataset directory with a `requirements.yml` file: [source] ---- my-project/ ├── pom.xml -├── reqstool/ +├── docs/reqstool/ │ └── requirements.yml (mandatory) └── src/ ---- @@ -68,7 +71,7 @@ Run `mvn verify` and the ZIP artifact will be created automatically. * Maven 3.9+ * Java 21+ -* A `requirements.yml` file in the dataset directory (default: `./reqstool/`) +* A `requirements.yml` file in the dataset directory (default: `reqstool/`) == License diff --git a/docs/modules/ROOT/pages/usage.adoc b/docs/modules/ROOT/pages/usage.adoc index 45fb5d6..ea94bb0 100644 --- a/docs/modules/ROOT/pages/usage.adoc +++ b/docs/modules/ROOT/pages/usage.adoc @@ -1,8 +1,8 @@ -== Usage += Usage -To use the reqstool Maven Plugin, add the following configuration to your Maven project's `pom.xml`: +== Basic usage -=== Basic Usage +Add the plugin to your `pom.xml` and set `datasetPath` if your dataset directory is not the default `reqstool/`: [source,xml] ---- @@ -19,14 +19,22 @@ To use the reqstool Maven Plugin, add the following configuration to your Maven + + ${project.basedir}/docs/reqstool + ---- -The plugin will automatically integrate with the standard Maven build lifecycle. +Run a standard build — the goal is bound to the `verify` phase automatically: -=== Annotation Dependency +[source,bash] +---- +mvn clean verify +---- + +== Annotation dependency To use `@Requirements` and `@SVCs` annotations in your code, add the annotations dependency: @@ -41,34 +49,31 @@ To use `@Requirements` and `@SVCs` annotations in your code, add the annotations ---- -=== Running Manually - -The goal can be invoked manually: +== Running the goal manually [source,bash] ---- mvn reqstool:assemble-and-attach-zip-artifact ---- -=== Available Goals - -==== assemble-and-attach-zip-artifact +== Goal reference -Main goal that: +=== assemble-and-attach-zip-artifact -* Bound to the `verify` phase (ensures tests have run) -* Combines annotation files -* Assembles ZIP artifact -* Attaches artifact for deployment +Default phase: `verify` -=== Default Lifecycle +Combines requirements and SVCs annotations into a single `annotations.yml`, +then (unless `skipAssembleZipArtifact` is set) assembles a ZIP artifact at +`/-reqstool.zip` and attaches it to the Maven project +with classifier `reqstool` and extension `zip`. -The plugin automatically integrates into the standard Maven build: +== Default lifecycle -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 +[source] +---- +verify + └── assemble-and-attach-zip-artifact + (runs after compile, test, integration-test phases) +---- -The ZIP artifact will be published with classifier `reqstool` (e.g., `my-app-1.0.0-reqstool.zip`). +ZIP artifact is written to `target/reqstool/-reqstool.zip`.