Gradle plugin for the requirement tracing suite OpenFastTrace.

• Blog
• Changelog
• Contributing guide
• OpenFastTrace stories

1. Preconditions: Java 17 and Gradle 8.6

2. Add plugin org.itsallcode.openfasttrace to your project:

   plugins { id "org.itsallcode.openfasttrace" version "3.1.0" }

3. Configure your project, see examples

4. Run

   ./gradlew traceRequirements

5. Report is written to build/reports/tracing.txt by default.

requirementTracing { failBuild = true inputDirectories = files('custom-dir') reportFile = file('build/custom-report.txt') reportFormat = 'plain' reportVerbosity = 'failure_details' detailsSectionDisplay = 'collapse' filteredArtifactTypes = ["req", "dsn"] }

You can configure the following properties:

• failBuild: Fail build when tracing finds any issues (default: true)
• inputDirectories: Files or directories to import
• reportFile: Path to the report file
• reportFormat: Format of the report
  • plain - Plain Text (default)
  • html - HTML
• reportVerbosity: Report verbosity
  • quiet - no output (in case only the return code is used)
  • minimal - display ok or not ok
  • summary - display only the summary, not individual specification items
  • failures - list of defect specification items
  • failure_summaries - list of summaries for defect specification items
  • failure_details - summaries and details for defect specification items (default)
  • all - summaries and details for all specification items
• detailsSectionDisplay: Initial display status of the details section in the HTML report
  • collapse - hide details (default)
  • expand - show details
• filteredArtifactTypes: Use only the listed artifact types during tracing

The short tag importer allows omitting artifact type and the covered artifact type. Optionally you can add a prefix to the item name, e.g. a common module name.

requirementTracing { tags { tag { paths = fileTree(dir: 'src/').include '*.impl.*' coveredItemNamePrefix = 'prefix' tagArtifactType = 'impl' coveredItemArtifactType = 'dsn' } tag { paths = fileTree(dir: 'src/').include '*.test.*' tagArtifactType = 'utest' coveredItemArtifactType = 'dsn' } } }

As a benefit the tags are much shorter and contain only the name and revision:

// [[tagname:1]]

See multi-project/sub1 for a basic example.

In bigger setups you might want to share requirements between multiple projects.

Example: The Software Architecture Design project swad contains overall requirements that must be fulfilled by projects component-a and component-b.

1. The swad project publishes its requirements as a zip file swad-req to a Maven repository.
2. Both components import these requirements and cover them in their Software Detailed Design (swdd).
3. Both components publish their requirements as artefacts component-a-req and component-b-req to the shared Maven repository.
4. A regular job check that all requirements from swad are covered by tracing swad-req, component-a-req and component-b-req.

If you want to publish requirements to a Maven repository you can use the following configuration in your build.gradle:

plugins { id 'org.itsallcode.openfasttrace' id 'maven-publish' } requirementTracing { inputDirectories = files('doc') } task requirementsZip(type: Zip, dependsOn: collectRequirements) { from collectRequirements.outputFile into '/' } publishing { publications { maven(MavenPublication) { artifact requirementsZip } } }

See publish-config for a basic example.

You can import requirements from another project using the importedRequirements configuration. The requirements must be published to a repository as a zip file and can be referenced using the usual gradle dependency syntax:

repositories { maven { url "http://repo.example.com/maven2" } } requirementTracing { importedRequirements = ['com.example:swad:1.0.0@zip'] }

See dependency-config for a basic example.

git clone https://github.com/itsallcode/openfasttrace-gradle.git cd openfasttrace-gradle ./gradlew check # Test report: build/reports/tests/index.html

To use openfasttrace from source during development:

1. Clone https://github.com/itsallcode/openfasttrace to ../openfasttrace

2. Create file gradle.properties with the following content:

   oftSourceDir = ../openfasttrace

./gradlew dependencyUpdates

Get token for OssIndex from ossindex.sonatype.org and add it to ~/.gradle/gradle.properties:

ossIndexUsername = <user> ossIndexToken = <token>

Then run

./gradlew ossIndexAudit

./gradlew clean sonar --info -Dsonar.token=[token]

1. Checkout the main branch, create a new branch.
2. Update version number in build.gradle and README.md.
3. Add changes in new version to CHANGELOG.md.
4. Commit and push changes.
5. Create a new pull request, have it reviewed and merged to main.

1. Start the release workflow

• Run command gh workflow run release.yml --repo itsallcode/openfasttrace-gradle --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. Plugin will be published at https://plugins.gradle.org/m2/org/itsallcode/openfasttrace/org.itsallcode.openfasttrace.gradle.plugin/