openfasttrace-gradle

Gradle plugin for the requirement tracing suite OpenFastTrace.

Project Information

• Blog
• Gradle Plugin page
• Changelog
• Contributing guide
• OpenFastTrace stories

Usage

1. Preconditions: Java 17 and Gradle 9.7.1 or later

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

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

3. Configure your project, see examples

4. Run

   ./gradlew traceRequirements

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

General Configuration

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

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)
  • direct_failure_details - details of non-transitive unclean items (added in OFT 4.6.0)
  • all - summaries and details for all specification items
• reportColorScheme: Color scheme of plain text report
  • black_and_white - Black and white (default)
  • monochrome - Monochrome (e.g for printers)
  • color - Color
• 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
• filterWantedStatuses: Import only specification items that have a status contained in the list of statuses. Possible values: draft, proposed, approved, rejected. See the OFT user guide for details.

Using OpenFastTrace Plugins

OpenFastTrace extension plugins can be added with the pluginDependencies property. The dependencies are added to the classpath used by requirement collection and tracing:

repositories {
  mavenCentral()
}

requirementTracing {
  pluginDependencies = ['org.itsallcode:openfasttrace-asciidoc-plugin:1.0.0']
}

These are OpenFastTrace extension plugins, not Gradle build plugins. Plugin JARs must provide the appropriate OpenFastTrace service descriptors and should not include a duplicate incompatible openfasttrace-api dependency. Plugin discovery remains additive to OpenFastTrace's built-in plugin directory.

Configuring the Short Tag Importer

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.

Sharing Requirements

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.

Publishing Requirements to a Maven Repository

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.

Importing External Requirements

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.

Development

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

Use openfasttrace From Source

To use openfasttrace from source during development:

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

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

   oftSourceDir = ../openfasttrace

Check if Dependencies are Up-to-date

./gradlew dependencyUpdates

Check Dependencies for Vulnerabilities

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

ossIndexUsername = <user>
ossIndexToken    = <token>

Then run

./gradlew ossIndexAudit

Run Sonar Analysis

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

Publish to plugins.gradle.org

Preparations

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.

Perform the Release

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/