### Install Initial Build Dependencies on Linux (Ubuntu/Debian) Source: https://github.com/itsallcode/openfasttrace/blob/main/doc/developer_guide.md Install OpenJDK 17 and Maven on Ubuntu or Debian systems if you intend to build OFT. ```bash apt-get install openjdk-17-jdk maven ``` -------------------------------- ### Start Release Workflow Source: https://github.com/itsallcode/openfasttrace/blob/main/doc/developer_guide.md Initiate the release process for the project. This can be done via the GitHub CLI or by manually triggering the `release.yml` workflow on GitHub Actions. ```sh gh workflow run release.yml --repo itsallcode/openfasttrace --ref main ``` -------------------------------- ### Tag Format with Revision and Name Source: https://github.com/itsallcode/openfasttrace/blob/main/doc/user_guide.md Examples demonstrating optional revision numbers and names within specification tags. ```java // [impl~~2->dsn~validate-authentication-request~1] ``` ```java // [impl~validate-password~2->dsn~validate-authentication-request~1] ``` -------------------------------- ### Report Trace to File with OFT in Java Source: https://github.com/itsallcode/openfasttrace/blob/main/doc/user_guide.md This example shows how to report trace results to a file using the OFT API with specified report settings. ```java // Reporting to a file oft.reportToPath(trace, reportPath, reportSettings); ``` -------------------------------- ### Requirement with Tags Source: https://github.com/itsallcode/openfasttrace/blob/main/doc/user_guide.md This example shows a requirement tagged with 'AuthenticationProvider', which can be used by development teams to filter specification items they are responsible for. ```text arch~authentication-provider-requires-valid-client-certificate~1 The authentication provider accepts only connections from clients offering a client certificate ... Needs: dsn Tags: AuthenticationProvider ``` -------------------------------- ### Report Trace to StdOut with OFT in Java Source: https://github.com/itsallcode/openfasttrace/blob/main/doc/user_guide.md This example demonstrates reporting trace results directly to standard output using the OFT API. ```java // Reporting to stdout oft.reportToStdOut(trace); ``` -------------------------------- ### Import, Link, Trace, and Report with OFT in Java Source: https://github.com/itsallcode/openfasttrace/blob/main/doc/user_guide.md This example shows how to use OFT for tracing and reporting. It imports items from a specified path, links them, traces the relationships, and reports the results to standard output. ```java import org.itsallcode.openfasttrace.Oft; import org.itsallcode.openfasttrace.core.LinkedSpecificationItem; import org.itsallcode.openfasttrace.core.SpecificationItem; import org.itsallcode.openfasttrace.core.Trace; final ImportSettings settings = ImportSettings \ .builder() \ .addInputs("/input/path") \ .build; final Oft oft = Oft.create(); final List items = oft.importItems(settings); final List linkedItems = oft.link(items); final Trace trace = oft.trace(linkedItems); oft.reportToStdOut(trace); if (trace.hasNoDefects()) { // ... do something } ``` -------------------------------- ### Run OpenFastTrace JAR from Command Line Source: https://github.com/itsallcode/openfasttrace/blob/main/README.md Execute the OpenFastTrace JAR file directly from the command line to trace a directory. Ensure you have Java 17 or later installed. ```sh java -jar product/target/openfasttrace-4.2.0.jar trace /path/to/directory/being/traced ``` -------------------------------- ### Forwarding Requirements Tag Format Source: https://github.com/itsallcode/openfasttrace/blob/main/doc/user_guide.md Example of using a tag to specify needed coverage from other artifact types, useful for UML models. ```java ' [dsn->req~1password-login~1>>impl,test] user -> system : login(token: OAuthToken) ``` -------------------------------- ### Forwarded Requirements Example Source: https://github.com/itsallcode/openfasttrace/blob/main/doc/user_guide.md It is recommended to place all forwards in a separate section with its own title to avoid confusion and ensure all requirements are processed correctly. ```text # Forwarded Requirements * dsn-->impl:req~bar~1 * dsn-->impl:req~zoo~2 * … ``` -------------------------------- ### Define Specification Item Description (Explicit) Source: https://github.com/itsallcode/openfasttrace/blob/main/doc/user_guide.md The `Description` keyword explicitly starts the descriptive text for a specification item. It must precede `Comment` or `Rationale`. ```text ### Specification item `feat~specification-item~1` Description: This is the description. ``` -------------------------------- ### Verify Identical Artifacts in Reproducible Build Source: https://github.com/itsallcode/openfasttrace/blob/main/doc/developer_guide.md Confirm that the build process generates identical artifacts across multiple runs from the same commit. This involves cleaning, installing, and then comparing artifacts. ```sh mvn -T 1C clean install -DskipTests mvn -T 1C clean verify artifact:compare -DskipTests ``` -------------------------------- ### SpecObject XML with Namespace Example Source: https://github.com/itsallcode/openfasttrace/blob/main/doc/user_guide.md This XML snippet demonstrates the SpecObject format extended with namespace support for custom XML elements. It includes a 'specobjects' element and an 'ext:extension' element. ```xml ``` -------------------------------- ### Basic Tag Format in Java Comment Source: https://github.com/itsallcode/openfasttrace/blob/main/doc/user_guide.md Example of embedding a basic tag within a Java comment to define specification items. ```java // [impl->dsn~validate-authentication-request~1] private validate(final AuthenticationRequest request){ // ... } ``` -------------------------------- ### Configure Maven Toolchains for JDK Versions Source: https://github.com/itsallcode/openfasttrace/blob/main/doc/developer_guide.md Create or update ~/.m2/toolchains.xml to configure the Maven Toolchains plugin for specific JDK versions. Adapt the jdkHome paths to your local JDK installations. ```xml jdk 17 /usr/lib/jvm/java-17-openjdk-amd64/ jdk 21 /usr/lib/jvm/java-21-openjdk-amd64/ jdk 25 /usr/lib/jvm/java-25-openjdk-amd64/ ``` -------------------------------- ### OFT Help Commands Source: https://github.com/itsallcode/openfasttrace/blob/main/doc/user_guide.md Equivalent commands to display a short help message, including command line usage and OFT version. ```bash oft -h ``` ```bash oft --help ``` ```bash oft help ``` -------------------------------- ### Display help text in OpenFastTrace Source: https://github.com/itsallcode/openfasttrace/blob/main/doc/changes/changes_3.5.0.md Use this command to view a short help text for the OpenFastTrace CLI. ```shell oft help ``` -------------------------------- ### Run Maven Verify (Unit, Integration Tests, and Checks) Source: https://github.com/itsallcode/openfasttrace/blob/main/doc/developer_guide.md Perform a full verification of the OpenFastTrace project, including unit tests, integration tests, and additional checks. The -T 1C flag enables parallel builds. ```sh mvn -T 1C verify ``` -------------------------------- ### Configure Ossindex Credentials Source: https://github.com/itsallcode/openfasttrace/blob/main/doc/developer_guide.md Set up credentials for the Ossindex service in the Maven settings file (`~/.m2/settings.xml`). This is required for checking vulnerabilities in dependencies. ```xml ossindex email@example.com token ``` -------------------------------- ### OFT Command Line Usage Source: https://github.com/itsallcode/openfasttrace/blob/main/doc/user_guide.md Displays the general command line structure for the OFT tool, including commands and options. ```bash oft command [option ...] [ ...] ``` ```bash oft --help ``` -------------------------------- ### Define Specification Item Description (Implicit) Source: https://github.com/itsallcode/openfasttrace/blob/main/doc/user_guide.md Any non-keyword text following a specification item ID is implicitly treated as its description, provided it does not start with another keyword. ```text ### Specification item `feat~specification-item~1` This is the description. ``` -------------------------------- ### Run Local Sonar Analysis Source: https://github.com/itsallcode/openfasttrace/blob/main/doc/developer_guide.md Perform a local SonarQube analysis of the project. Replace `[token]` with your SonarQube token. The analysis includes cleaning the project, packaging, and then running Sonar. ```sh mvn -T 1C clean package sonar:sonar -Dsonar.token=[token] ``` -------------------------------- ### Build Maven Deployment Bundle Source: https://github.com/itsallcode/openfasttrace/blob/main/doc/developer_guide.md Execute this Maven command to build a deployment bundle for verification. It skips tests and prevents actual publishing to Maven Central, allowing inspection of the bundle's contents. Use this to ensure only intended modules are packaged for release. ```bash mvn -T1C deploy -PcentralPublishing -DcentralPublishingSkipPublishing=true -DskipTests ``` -------------------------------- ### Build OpenFastTrace JAR (Skip Tests) Source: https://github.com/itsallcode/openfasttrace/blob/main/doc/developer_guide.md Package the OpenFastTrace project into an executable JAR, skipping the execution of tests. The -T 1C flag enables parallel builds. ```sh mvn -T 1C package -DskipTests ``` -------------------------------- ### Check for Dependency and Plugin Updates Source: https://github.com/itsallcode/openfasttrace/blob/main/doc/developer_guide.md Display a list of dependencies and plugins that have newer versions available. This command helps identify outdated components in the project. ```sh mvn versions:display-dependency-updates versions:display-plugin-updates ``` -------------------------------- ### Trace All Artifacts in Project Directory Source: https://github.com/itsallcode/openfasttrace/blob/main/doc/user_guide.md Trace all artifacts within specified directories. Useful for projects with a clear directory structure. Assumes artifacts are readable. ```sh PROJECT_ROOT='/home/git/my-project/' oft trace "$PROJECT_ROOT"/doc "$PROJECT_ROOT"/src/main/java "$PROJECT_ROOT"/src/test/java ``` -------------------------------- ### Run Maven Unit Tests Source: https://github.com/itsallcode/openfasttrace/blob/main/doc/developer_guide.md Execute unit tests for the OpenFastTrace project using Maven. The -T 1C flag enables parallel builds. ```sh mvn -T 1C test ``` -------------------------------- ### OFT Requirement with Rationale and Comment Source: https://github.com/itsallcode/openfasttrace/blob/main/doc/user_guide.md Includes a 'Rationale' section to explain the reason for a requirement and a 'Comment' section for explanatory notes or warnings. ```markdown `arch~acme-client-uses-exponential-back-off-strategy~1` If the ACME client cannot reach the ACME server, it uses a back-off strategy with exponentially growing retry interval. Rationale: If the ACME server comes up again after a failure, it would be under heavy load immediately if all clients tried to reestablish their connections at the same time. ... Comment: Since the implementation depends on the hardware capabilities of the client, the details are up to the detailed design. Needs: dsn ``` -------------------------------- ### PlantUML Sequence Diagram for Import Process Source: https://github.com/itsallcode/openfasttrace/blob/main/doc/spec/design.md Illustrates the interaction between MultiFileImporterImpl, ImporterFactoryLoader, ImporterFactory, and Importer during the file import process. It shows how an importer is selected based on file support and priority. ```plantuml @startuml participant MultiFileImporterImpl as MFI participant ImporterFactoryLoader as IFL participant ImporterFactory as IF participant Importer as I participant SpecificationListBuilder as SLB [-> MFI : importFile(file) activate MFI MFI -> IFL : getImporterFactory(file) activate IFL IFL -> IF : supportsFile(file) activate IF return true IFL -> IF : getPriority() activate IF return priority note over IFL: Choose factory with\nlowest priority value return factory MFI -> IF : createImporter(file, specItemBuilder) activate IF create I IF -> I : new return importer MFI -> I : runImport() activate I I -> SLB : event(item) activate SLB return return return @enduml ``` -------------------------------- ### Import and Export Specification Items in Java Source: https://github.com/itsallcode/openfasttrace/blob/main/doc/user_guide.md This snippet demonstrates how to use the OFT API to import specification items from the current directory and export them to a ReqM2 file. ```java import org.itsallcode.openfasttrace.Oft; import org.itsallcode.openfasttrace.core.SpecificationItem; final Oft oft = Oft.create(); final List items = oft.importItems(settings); oft.exportToPath(items, Paths.get("/output/path/export.oreqm")); ``` -------------------------------- ### Configure Maven Central Credentials Source: https://github.com/itsallcode/openfasttrace/blob/main/doc/developer_guide.md Set up your Maven Central username and password in the `~/.m2/settings.xml` file. This is required for authentication when interacting with Maven Central. ```xml central user password ``` -------------------------------- ### Output Format Option Source: https://github.com/itsallcode/openfasttrace/blob/main/doc/user_guide.md Specifies the format for the tracing report. Defaults to 'plain'. ```bash -o, --output-format ``` -------------------------------- ### Specify Needed Artifact Types (List) Source: https://github.com/itsallcode/openfasttrace/blob/main/doc/user_guide.md The `Needs` keyword can also be used as a list to specify required artifact types. Mixing list and one-liner styles is not allowed. ```text Needs: - dsn - uman ``` -------------------------------- ### Run Single Integration Test Source: https://github.com/itsallcode/openfasttrace/blob/main/doc/developer_guide.md Execute a specific integration test class using Maven. Specify the test class with the `it.test` system property and the module with the `-projects` command-line option. ```sh mvn -Dit.test=CliStarterIT failsafe:integration-test -projects product ``` -------------------------------- ### Evolution of Requirement Tracing Tools Source: https://github.com/itsallcode/openfasttrace/blob/main/doc/about_us.md This diagram illustrates the lineage of OpenFastTrace (OFT) from its predecessors, showing the timeline of their development. ```text ReqMgr ReqMgrNG ReqM/ReqM2 Allosaurus OFT OFT 1.0 | | T-Reqs | | | | --+---------+--+---------+-------------+-----------+-------+-------+-> t 2003 2004 ~2012 2015 2018 ``` -------------------------------- ### Verify Reproducible Build Configuration Source: https://github.com/itsallcode/openfasttrace/blob/main/doc/developer_guide.md Check the configuration for reproducible builds, which ensures that building from the same Git commit always produces identical artifacts. This command is part of the `verify` phase. ```sh mvn initialize artifact:check-buildplan ``` -------------------------------- ### HTML Report Details Display Option Source: https://github.com/itsallcode/openfasttrace/blob/main/doc/user_guide.md Sets the initial display status for the details section in HTML reports. Defaults to 'collapse'. ```bash --details-section-display ``` -------------------------------- ### Output File Option Source: https://github.com/itsallcode/openfasttrace/blob/main/doc/user_guide.md Specifies the output file path for the report or converted requirements. Defaults to STDOUT. ```bash -f, --output-file ``` -------------------------------- ### Clone OpenFastTrace Git Repository Source: https://github.com/itsallcode/openfasttrace/blob/main/doc/developer_guide.md Clone the OpenFastTrace project from its GitHub repository to your local machine. ```sh git clone https://github.com/itsallcode/openfasttrace.git ``` -------------------------------- ### Run Requirements Tracing Source: https://github.com/itsallcode/openfasttrace/blob/main/doc/developer_guide.md Execute the self-tracing script for requirements. This is a standalone script for tracing requirements within the project. ```sh ./oft-self-trace.sh ``` -------------------------------- ### Update Dependencies and Plugins to Latest Releases Source: https://github.com/itsallcode/openfasttrace/blob/main/doc/developer_guide.md Automatically upgrade project dependencies and properties to their latest stable release versions. The `--update-snapshots` flag ensures that the latest available versions are considered. ```sh mvn -T 1C --update-snapshots versions:use-latest-releases versions:update-properties ``` -------------------------------- ### Log Level Option Source: https://github.com/itsallcode/openfasttrace/blob/main/doc/user_guide.md Sets the log level for console logging. Defaults to 'WARNING'. ```bash -l, --log-level ``` -------------------------------- ### Check for Vulnerabilities with Ossindex Source: https://github.com/itsallcode/openfasttrace/blob/main/doc/developer_guide.md Audit project dependencies for known vulnerabilities using the Ossindex Maven plugin. This command should be run after configuring credentials. ```sh mvn -T 1C test-compile org.sonatype.ossindex.maven:ossindex-maven-plugin:audit org.sonatype.ossindex.maven:ossindex-maven-plugin:audit-aggregate ``` -------------------------------- ### Add OpenFastTrace Dependency via Gradle Source: https://github.com/itsallcode/openfasttrace/blob/main/doc/developer_guide.md Add this to your Gradle project to use OpenFastTrace as a dependency. ```groovy dependencies { compile "org.itsallcode.openfasttrace:openfasttrace:4.2.0" } ``` -------------------------------- ### Color Scheme Option Source: https://github.com/itsallcode/openfasttrace/blob/main/doc/user_guide.md Changes the output color scheme for console logging. Available schemes are 'black-and-white', 'monochrome', and 'color'. ```bash -c, --color= ``` -------------------------------- ### Requirement Summary Line Source: https://github.com/itsallcode/openfasttrace/blob/main/doc/user_guide.md Displays the status, incoming/outgoing link counts, specification ID, and artifact coverage for a requirement. ```text ok [ in: 2 / 2 ✔ | out: 1 / 1 ✔ ] dsn~cli.tracing.default-format~1 (impl, utest) ``` -------------------------------- ### Import Artifact Types Option Source: https://github.com/itsallcode/openfasttrace/blob/main/doc/user_guide.md Use this option to filter imports by specifying desired artifact types. ```bash -a, --wanted-artifact-types [,...] ``` -------------------------------- ### Incoming Link Detail Source: https://github.com/itsallcode/openfasttrace/blob/main/doc/user_guide.md Details an incoming link, showing the artifact type and its specific ID, indicating coverage. ```text [covered shallow ] ← impl~cli.tracing.default-format-2215031703~0 ``` -------------------------------- ### Specify Java Version for Maven Build Source: https://github.com/itsallcode/openfasttrace/blob/main/doc/developer_guide.md Add the -Djava.version argument to your Maven command to build and test OpenFastTrace with a specific Java version, overriding the default of Java 17. ```sh mvn -Djava.version=17 package -DskipTests ``` -------------------------------- ### Upload Bundle to Maven Central for Validation Source: https://github.com/itsallcode/openfasttrace/blob/main/doc/developer_guide.md Execute this Maven command to upload your bundle to Maven Central for validation without actually publishing it. Ensure you have configured your credentials in `settings.xml`. ```sh mvn -T1C clean deploy -PcentralPublishing -DcentralPublishingSkipPublishing=true -DcentralPublishingAutoPublish=false -DskipTests ``` -------------------------------- ### Define Specification Item Dependencies Source: https://github.com/itsallcode/openfasttrace/blob/main/doc/user_guide.md The `Depends` keyword lists other specification items that the current item relies on. Each dependency is on a new line, preceded by a bullet. ```text ### Depending specification item `req~depending-item~1` This item depends on two others. Depends: - req~dependency-1~1 - req~dependency-2~1 ``` -------------------------------- ### Configure OFT Reporting Format in Java Source: https://github.com/itsallcode/openfasttrace/blob/main/doc/user_guide.md This snippet demonstrates how to configure the reporting format for OFT using the ReportSettings builder. It sets the output format to HTML. ```java ReportSettings reportSettings = ReportSettings.builder().outputFormat("html").build(); ``` -------------------------------- ### Configure Logging Properties Source: https://github.com/itsallcode/openfasttrace/blob/main/doc/developer_guide.md Specify a custom configuration file for Java's built-in logging system. This allows control over log levels and formatting. ```sh -Djava.util.logging.config.file=src/test/resources/logging.properties ``` -------------------------------- ### OFT Requirement with Coverage Needs Source: https://github.com/itsallcode/openfasttrace/blob/main/doc/user_guide.md Specifies artifact types that must cover the requirement. 'Needs: dsn, uman' indicates coverage is required in design and user manual documents. ```markdown ### The Requirement Title `req~this-is-the-id~1` This is the description of the requirement. Needs: dsn, uman ``` -------------------------------- ### Specify item name in coverage tags Source: https://github.com/itsallcode/openfasttrace/blob/main/doc/changes/changes_3.9.0.md Use this syntax to include item names directly within coverage tags for improved traceability. ```text [impl~validate-password~2->dsn~validate-authentication-request~1] ``` -------------------------------- ### Generate HTML Tracing Reports Source: https://github.com/itsallcode/openfasttrace/blob/main/doc/user_guide.md Generate tracing reports in HTML format for a more visually appealing output. Useful for management or quality assessors. ```sh oft trace -o html ``` -------------------------------- ### Requirement Coverage Details Source: https://github.com/itsallcode/openfasttrace/blob/main/doc/user_guide.md This snippet shows how a requirement's coverage by other requirements is detailed within the XML report. It includes elements for the covered requirement's type, ID, version, and doctype. ```xml arch-requirement 1 arch ... ``` -------------------------------- ### Minimal OFT Requirement Source: https://github.com/itsallcode/openfasttrace/blob/main/doc/user_guide.md A basic OFT requirement consists of an ID and a description. This is the simplest valid requirement format. ```markdown `req~this-is-the-id~1` This is the description of the requirement. ```