Skip to content

docs: add complete configuration reference table to README #160

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jimisola merged 2 commits into from
Apr 19, 2026
Merged

docs: add complete configuration reference table to README #160

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
13a1b1c
docs: add complete configuration reference table to README
jimisola Apr 18, 2026
987f6cd
docs: update Antora docs with configuration reference table and usage…
jimisola Apr 18, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
79 changes: 79 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`:
Expand All @@ -34,6 +36,83 @@ Add the plugin to your `pom.xml`:
</plugin>
```

## 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
<plugin>
<groupId>io.github.reqstool</groupId>
<artifactId>reqstool-maven-plugin</artifactId>
<version>1.0.4</version>
<executions>
<execution>
<goals>
<goal>assemble-and-attach-zip-artifact</goal>
</goals>
</execution>
</executions>
<configuration>
<requirementsAnnotationsFile>
${project.build.directory}/generated-sources/annotations/resources/annotations.yml
</requirementsAnnotationsFile>
<svcsAnnotationsFile>
${project.build.directory}/generated-test-sources/test-annotations/resources/annotations.yml
</svcsAnnotationsFile>
<outputDirectory>${project.build.directory}/reqstool</outputDirectory>
<datasetPath>${project.basedir}/docs/reqstool</datasetPath>
<testResults>
<testResult>target/surefire-reports/**/*.xml</testResult>
<testResult>target/failsafe-reports/**/*.xml</testResult>
</testResults>
<skip>false</skip>
<skipAssembleZipArtifact>false</skipAssembleZipArtifact>
<skipAttachZipArtifact>false</skipAttachZipArtifact>
</configuration>
</plugin>
```

### 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 `<outputDirectory>/<finalName>-reqstool.zip`. The ZIP is attached to the Maven project with classifier `reqstool` and extension `zip`.

## Usage

```bash
Expand Down
190 changes: 82 additions & 108 deletions docs/modules/ROOT/pages/configuration.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,141 +1,115 @@
== Configuration
= Configuration

The plugin provides sensible defaults, but you can customize if needed by adding a `<configuration>` 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 `<configuration>` block in your `pom.xml`.

=== Complete Configuration Example
== Configuration reference

[source,xml]
----
<configuration>
<!-- Path to requirements annotations YAML -->
<!-- Default: ${project.build.directory}/generated-sources/annotations/resources/annotations.yml -->
<requirementsAnnotationsFile>
${project.build.directory}/generated-sources/annotations/resources/annotations.yml
</requirementsAnnotationsFile>
[cols="1,1,2,2",options="header"]
|===
|Parameter |Type |Default |Description

<!-- Path to SVCS (Software Verification Cases) annotations YAML -->
<!-- Default: ${project.build.directory}/generated-test-sources/test-annotations/resources/annotations.yml -->
<svcsAnnotationsFile>
${project.build.directory}/generated-test-sources/test-annotations/resources/annotations.yml
</svcsAnnotationsFile>
|`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

<!-- Output directory for ZIP and combined annotations -->
<!-- Default: ${project.build.directory}/reqstool -->
<outputDirectory>${project.build.directory}/reqstool</outputDirectory>
|`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

<!-- Dataset directory containing requirements.yml and optional files -->
<!-- Default: ${project.basedir}/reqstool -->
<datasetPath>${project.basedir}/reqstool</datasetPath>
|`outputDirectory`
|`File`
|`${project.build.directory}/reqstool`
|Output directory for the ZIP artifact and combined `annotations.yml`

<!-- Test result file patterns (Ant-style) -->
<testResults>
<testResult>target/surefire-reports/**/*.xml</testResult>
<testResult>target/failsafe-reports/**/*.xml</testResult>
</testResults>
|`datasetPath`
|`File`
|`${project.basedir}/reqstool`
|Directory containing `requirements.yml` and optional supporting files

<!-- Skip entire plugin execution (default: false) -->
<skip>false</skip>
|`testResults`
|`String[]`
|_(none)_
|Ant-style glob patterns for test result XML files to include in the ZIP

<!-- Skip ZIP assembly but keep annotation combining (default: false) -->
<skipAssembleZipArtifact>false</skipAssembleZipArtifact>
|`skip`
|`boolean`
|`false`
|Skip all plugin execution

<!-- Skip artifact attachment for deployment (default: false) -->
<skipAttachZipArtifact>false</skipAttachZipArtifact>
</configuration>
----

=== 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]
----
<requirementsAnnotationsFile>
${project.build.directory}/generated-sources/annotations/resources/annotations.yml
</requirementsAnnotationsFile>
----
|`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]
----
<svcsAnnotationsFile>
${project.build.directory}/generated-test-sources/test-annotations/resources/annotations.yml
</svcsAnnotationsFile>
----
[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]
----
<outputDirectory>${project.build.directory}/reqstool</outputDirectory>
----
|`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]
----
<datasetPath>${project.basedir}/reqstool</datasetPath>
----

==== testResults

The `testResults` parameter specifies one or more test result file patterns.
Supports Ant-style pattern matching.

[source,xml]
----
<testResults>
<testResult>target/surefire-reports/**/*.xml</testResult>
<testResult>target/failsafe-reports/**/*.xml</testResult>
</testResults>
----

==== skip

Skip the execution of the entire plugin.
Defaults to `false`.

[source,xml]
----
<skip>false</skip>
<configuration>
<datasetPath>${project.basedir}/docs/reqstool</datasetPath>
</configuration>
----

==== skipAssembleZipArtifact

Skip ZIP artifact assembly but continue with annotation combining.
Defaults to `false`.
== Complete configuration example

[source,xml]
----
<skipAssembleZipArtifact>false</skipAssembleZipArtifact>
<configuration>
<requirementsAnnotationsFile>
${project.build.directory}/generated-sources/annotations/resources/annotations.yml
</requirementsAnnotationsFile>
<svcsAnnotationsFile>
${project.build.directory}/generated-test-sources/test-annotations/resources/annotations.yml
</svcsAnnotationsFile>
<outputDirectory>${project.build.directory}/reqstool</outputDirectory>
<datasetPath>${project.basedir}/docs/reqstool</datasetPath>
<testResults>
<testResult>target/surefire-reports/**/*.xml</testResult>
<testResult>target/failsafe-reports/**/*.xml</testResult>
</testResults>
<skip>false</skip>
<skipAssembleZipArtifact>false</skipAssembleZipArtifact>
<skipAttachZipArtifact>false</skipAttachZipArtifact>
</configuration>
----

==== 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]
----
<skipAttachZipArtifact>false</skipAttachZipArtifact>
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
21 changes: 12 additions & 9 deletions docs/modules/ROOT/pages/index.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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]
----
Expand All @@ -29,35 +29,38 @@ This Maven plugin generates a ZIP artifact containing combined annotations and v
</goals>
</execution>
</executions>
<configuration>
<datasetPath>${project.basedir}/docs/reqstool</datasetPath>
</configuration>
</plugin>
</plugins>
</build>
----

== 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/
----
Expand All @@ -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

Expand Down
Loading
Loading