openfasttrace-maven-plugin

Maven Plugin for OpenFastTrace (OFT).

Project Information

Sonarcloud status:

• Blog
• Changelog
• Contributing guide
• OpenFastTrace stories

Usage

Add the openfasttrace-maven-plugin to your pom.xml:

<plugin>
    <groupId>org.itsallcode</groupId>
    <artifactId>openfasttrace-maven-plugin</artifactId>
    <version>2.3.0</version>
    <executions>
        <execution>
            <id>trace-requirements</id>
            <goals>
                <goal>trace</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <failBuild>true</failBuild>
        <reportOutputFormat>html</reportOutputFormat>
        <reportVerbosity>ALL</reportVerbosity>
        <reportShowOrigin>true</reportShowOrigin>
        <detailsSectionDisplay>COLLAPSE</detailsSectionDisplay>
        <artifactTypes>feat,req</artifactTypes>
        <tags>prototype,mvp</tags>
    </configuration>
</plugin>

Then you can run tracing by calling the goal directly: mvn openfasttrace:trace.

The plugin binds to the verify lifecycle, so you can also use mvn verify.

See src/test/resources/empty-project for an example project.

OpenFastTrace Plugins

You can use OpenFastTrace plugins to import and export requirements in additional formats. Include plugins by adding them as a dependency to the openfasttrace-maven-plugin, see project-with-plugins as an example.

<plugin>
    <groupId>org.itsallcode</groupId>
    <artifactId>openfasttrace-maven-plugin</artifactId>
    <version>2.3.0</version>
    <configuration>
        <failBuild>true</failBuild>
    </configuration>
    <dependencies>
        <dependency>
            <groupId>org.itsallcode</groupId>
            <artifactId>openfasttrace-asciidoc-plugin</artifactId>
            <version>0.2.0</version>
        </dependency>
    </dependencies>
</plugin>

Configuration

You can configure the plugin using the <configuration> element.

Traced Directories

By default the OFT plugin imports requirements from the following directories:

• The doc sub-directory of the module that includes the plugin if it exists
• For each Maven module in the project if they exist:
  • Compile source roots (default: src/main/java)
  • Resources (default: src/main/resources)
  • Test compile source roots (default: src/test/java)
  • Test resources (default: src/test/resources)

Adding Custom Source Directories

You can add additional custom source directories using the Build Helper Maven Plugin.

Please note that the phases generate-sources and generate-test-sources have nothing to do with the phase in which OFT does its job, rather it defines in which phase the directory is added to the list of known source directories by the build-helper-maven-plugin.

The following snipped adds source directory src/main/rust and test source directory src/test/rust:

<plugin>
    <groupId>org.codehaus.mojo</groupId>
    <artifactId>build-helper-maven-plugin</artifactId>
    <version>3.6.0</version>
    <executions>
        <execution>
            <id>add-source</id>
            <phase>generate-sources</phase>
            <goals>
                <goal>add-source</goal>
            </goals>
            <configuration>
                <sources>
                    <source>src/main/rust</source>
                </sources>
            </configuration>
        </execution>
        <execution>
            <id>add-test-source</id>
            <phase>generate-test-sources</phase>
            <goals>
                <goal>add-test-source</goal>
            </goals>
            <configuration>
                <sources>
                    <source>src/test/rust</source>
                </sources>
            </configuration>
        </execution>
    </executions>
</plugin>

Adding Custom Resource Directories

You can add additional resource directories using the Maven Resources Plugin. The following snipped adds src/custom-resources as additional resource directory:

<build>
    <resources>
        <resource>
            <directory>src/custom-resources</directory>
        </resource>
    </resources>
</build>

Selecting the Imported Specification Items

Sometimes you don't want to trace the whole requirement chain. Instead, you are interested in the consistency of a subset. For instance, if you need to deliver a system requirement specification to another team, your job is to assure that the document is consistent in itself.

For those cases you can add an include list to the configuration that explicitly lists all artifact types or tags to be imported. Note that this also affects which required coverage is imported — which is exactly what you want in this situation.

See the OFT user guide on import options for details.

Select Artifact Types

The following example configuration limits import to artifact types feat and req.

<configuration>
    <artifactTypes>feat,req</artifactTypes>
</configuration>

This works similar to OFT's command line argument --wanted-artifact-types.

Select Tags

The following example configuration limits import to tags prototype and mvp.

<configuration>
    <tags>prototype,mvp</tags>
</configuration>

This works similar to OFT's command line argument --wanted-tags.

You can specify the underscore _ to import specification items without tags.

You can also specify the tags to import using CLI option -Dtags=prototype,mvp.

Report

Report Format

The tracing report is in HTML format by default. You can configure plain text format with <reportOutputFormat>plain</reportOutputFormat>.

Report Location

The tracing report will be written to target/tracing-report.html by default. You can configure the location with <outputDirectory>${project.build.directory}/reports/</outputDirectory>.

HTML Report Details Section Display

The HTML report will have its details sections collapsed (i.e. hidden) by default. You can render the HTML with expanded details sections with <detailsSectionDisplay>EXPAND</detailsSectionDisplay>.

Fail Build

By default the build will fail when there are errors found during tracing. To continue with the build when tracing fails, use configuration <failBuild>false</failBuild>.

Skipping Execution

To skip execution of the plugin, add command line option -Dopenfasttrace.skip=true when running Maven.

Development

Installation of Initial Build Dependencies on Linux

Ubuntu or Debian

If you want to build OFT:

apt-get install openjdk-17-jdk maven

Configure Maven Toolchain

This project uses Maven Toolchains to configure the correct JDK version (see the documentation for details). To configure the Toolchains plugin create file ~/.m2/toolchains.xml with the following content. Adapt the paths to your JDKs.

<toolchains xmlns="http://maven.apache.org/TOOLCHAINS/1.1.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/TOOLCHAINS/1.1.0 http://maven.apache.org/xsd/toolchains-1.1.0.xsd">
    <toolchain>
        <type>jdk</type>
        <provides>
            <version>17</version>
        </provides>
        <configuration>
            <jdkHome>/usr/lib/jvm/java-17-openjdk-amd64/</jdkHome>
        </configuration>
    </toolchain>
        <toolchain>
        <type>jdk</type>
        <provides>
            <version>21</version>
        </provides>
        <configuration>
            <jdkHome>/usr/lib/jvm/java-21-openjdk-amd64/</jdkHome>
        </configuration>
    </toolchain>
</toolchains>

Essential Build Steps

• git clone https://github.com/itsallcode/openfasttrace-maven-plugin.git
• Run mvn test to run unit tests.
• Run mvn integration-test to run integration tests.

Using Eclipse

Import as a Maven project using "File" → "Import..." → "Maven" → "Existing Maven Projects"

Run local sonar analysis

sonar_token="[token]"
mvn clean org.jacoco:jacoco-maven-plugin:prepare-agent package sonar:sonar \
    -Dsonar.login=$sonar_token

See analysis results at https://sonarcloud.io/dashboard?id=org.itsallcode%3Aopenfasttrace-maven-plugin

Check for updated dependencies / plugins

Display dependencies and plugins with newer versions:

mvn --update-snapshots versions:display-dependency-updates versions:display-plugin-updates

Automatically upgrade dependencies:

mvn --update-snapshots versions:use-latest-releases versions:update-properties

Creating a Release on Maven Central and GitHub

Prepare the Release

1. Checkout the main branch.
2. Update version in pom.xml, CHANGELOG.md and README.md.
3. Commit and push changes.
4. Create a new pull request, have it reviewed and merged to main.

Perform the Release

1. Start the release workflow

• Run command gh workflow run release.yml --repo itsallcode/openfasttrace-maven-plugin --ref main
• or go to GitHub Actions and start the release.yml workflow on branch main.

2. Update title and description of the newly created GitHub release.
3. After some time the release will be available at Maven Central.