Gradle plugin for the requirement tracing suite OpenFastTrace.
-
Preconditions: Java 17 and Gradle 8.6
-
Add plugin
org.itsallcode.openfasttrace
to your project:plugins { id "org.itsallcode.openfasttrace" version "3.0.0" }
-
Configure your project, see examples
-
Run
./gradlew traceRequirements
-
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'
}
You can configure the following properties:
failBuild
: Fail build when tracing finds any issues (default:true
)inputDirectories
: Files or directories to importreportFile
: Path to the report filereportFormat
: Format of the reportplain
- Plain Text (default)html
- HTML
reportVerbosity
: Report verbosityquiet
- no output (in case only the return code is used)minimal
- display ok or not oksummary
- display only the summary, not individual specification itemsfailures
- list of defect specification itemsfailure_summaries
- list of summaries for defect specification itemsfailure_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 reportcollapse
- hide details (default)expand
- show details
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
.
- The
swad
project publishes its requirements as a zip fileswad-req
to a Maven repository. - Both components import these requirements and cover them in their Software Detailed Design (swdd).
- Both components publish their requirements as artefacts
component-a-req
andcomponent-b-req
to the shared Maven repository. - A regular job check that all requirements from
swad
are covered by tracingswad-req
,component-a-req
andcomponent-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 "https://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:
-
Clone https://github.com/itsallcode/openfasttrace to
../openfasttrace
-
Create file
gradle.properties
with the following content:oftSourceDir = ../openfasttrace
./gradlew dependencyUpdates
./gradlew ossIndexAudit
./gradlew clean sonar --info -Dsonar.token=[token]
- Checkout the
main
branch, create a new branch. - Update version number in
build.gradle
andREADME.md
. - Add changes in new version to
CHANGELOG.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-gradle --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.
- Plugin will be published at https://plugins.gradle.org/m2/org/itsallcode/openfasttrace/org.itsallcode.openfasttrace.gradle.plugin/