Maven Plugin for OpenFastTrace (OFT).
Sonarcloud status:
Add the openfasttrace-maven-plugin to your pom.xml
:
<plugin>
<groupId>org.itsallcode</groupId>
<artifactId>openfasttrace-maven-plugin</artifactId>
<version>2.2.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>
</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.
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.2.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>
You can configure the plugin using the <configuration>
element.
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
)
- Compile source roots (default:
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>
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>
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 to be imported. Note that this also affects which required coverage is imported — which is exactly what you want in this situation.
The following example configuration limits import to artifact types feat
and req
.
<configuration>
<artifactTypes>feat,req</artifactTypes>
</configuration>
The tracing report is in HTML format by default. You can configure plain text format with <reportOutputFormat>plain</reportOutputFormat>
.
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>
.
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>
.
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>
.
To skip execution of the plugin, add command line option -Dopenfasttrace.skip=true
when running Maven.
If you want to build OFT:
apt-get install openjdk-17-jdk maven
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="https://maven.apache.org/TOOLCHAINS/1.1.0"
xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="https://maven.apache.org/TOOLCHAINS/1.1.0 https://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>
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.
Import as a Maven project using "File" → "Import..." → "Maven" → "Existing Maven Projects"
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
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
- Checkout the
main
branch. - Update version in
pom.xml
,CHANGELOG.md
andREADME.md
. - Commit and push changes.
- Create a new pull request, have it reviewed and merged to
main
.
- 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 branchmain
.
- Update title and description of the newly created GitHub release.
- After some time the release will be available at Maven Central.