diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml index c06aa3d3e..92e42de65 100644 --- a/.github/workflows/gh-pages.yml +++ b/.github/workflows/gh-pages.yml @@ -3,7 +3,16 @@ name: Deploy GitHub Pages on: push: branches: ["main"] + pull_request: + release: + types: [published] workflow_dispatch: + inputs: + deploy: + description: "Deploy to GitHub Pages" + required: false + type: boolean + default: true concurrency: group: "pages" @@ -13,6 +22,8 @@ jobs: build: permissions: contents: read + pages: write + id-token: write runs-on: ubuntu-latest steps: - name: Checkout @@ -24,15 +35,24 @@ jobs: - name: Build with Jekyll uses: actions/jekyll-build-pages@v1 with: - source: ./doc + source: . destination: ./_site + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + JEKYLL_GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - name: Upload artifact uses: actions/upload-pages-artifact@v5 with: path: ./_site/ + - name: Upload build artifact + uses: actions/upload-artifact@v7 + with: + name: github-pages-preview + path: ./_site/ deploy: - if: ${{ github.ref == 'refs/heads/main' }} + # Publishing on push to main, release or manual dispatch. + if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' || github.event_name == 'release' || (github.event_name == 'workflow_dispatch' && (inputs.deploy || inputs.deploy == null)) }} permissions: id-token: write pages: write diff --git a/AGENTS.md b/AGENTS.md index 63e62c9a9..35b1b0025 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -108,8 +108,9 @@ Needs: impl, utest - **Detailed Skills**: See [`.agents/skills`](.agents/skills) for domain knowledge (ID syntax, keywords). - **Key Resources**: - `README.md`: General overview. - - `doc/developer_guide.md`: Detailed build and internal info. + - `doc/developer_guide/developer_guide.md`: Detailed build and internal info. - `doc/user_guide/user_guide.md`: Comprehensive tool usage. + - `doc/terminology.md`: Unified terminology for all documents. - `CONTRIBUTING.md`: Human-AI collaboration guidelines. - `doc/spec/system_requirements.md`: System requirements specification. - `doc/spec/design.md`: High-level design documentation. diff --git a/CNAME b/CNAME new file mode 100644 index 000000000..e4d4f45ed --- /dev/null +++ b/CNAME @@ -0,0 +1 @@ +openfasttrace.itsallcode.org diff --git a/Gemfile b/Gemfile new file mode 100644 index 000000000..f3630097b --- /dev/null +++ b/Gemfile @@ -0,0 +1,5 @@ +source "https://rubygems.org" +gem "github-pages", group: :jekyll +gem "jekyll-remote-theme" +gem "jekyll-include-cache" +gem "faraday-retry" diff --git a/README.md b/README.md index 0a9791940..caa65fa8d 100644 --- a/README.md +++ b/README.md @@ -32,6 +32,7 @@ Sonarcloud status: **User Guides and Tools** * [๐Ÿ“– User Guide](doc/user_guide/user_guide.md) +* [๐Ÿ“š Terminology](doc/terminology.md) * [๐Ÿ”Œ Extending OpenFastTrace With Plugins](doc/plugins.md) * [๐Ÿ’ฒ Command Line Usage](core/src/main/resources/usage.txt) * [๐Ÿ›  IntelliJ Plugin (PyCharm, Clion, etc.)](https://github.com/itsallcode/openfasttrace-intellij-plugin) @@ -52,8 +53,8 @@ Sonarcloud status: **Information for Contributors** * [๐ŸŽŸ๏ธ Project Board](https://github.com/orgs/itsallcode/projects/3/views/1) -* [๐Ÿฆฎ Developer Guide](doc/developer_guide.md) -* [๐Ÿ”Œ Plugin Developer Guide](doc/plugin_developer_guide.md) +* [๐Ÿฆฎ Developer Guide](doc/developer_guide/developer_guide.md) +* [๐Ÿ”Œ Plugin Developer Guide](doc/developer_guide/plugin_developer_guide.md) * [๐ŸŽ Contributing Guide](CONTRIBUTING.md) * [๐Ÿค Code of Conduct](CODE_OF_CONDUCT.md) * [๐Ÿค– AI Agent Guide](AGENTS.md) @@ -84,7 +85,7 @@ Pre-Built JAR files (called `openfasttrace-4.9.0.jar`) are available from the fo * [Maven Central](https://repo1.maven.org/maven2/org/itsallcode/openfasttrace/openfasttrace/4.9.0/openfasttrace-4.9.0.jar) * [GitHub](https://github.com/itsallcode/openfasttrace/releases/download/4.9.0/openfasttrace-4.9.0.jar) -Check our [developer guide](doc/developer_guide.md#getting-the-openfasttrace-library) to learn how to use the OFT JAR as dependency in your own code with popular build tools. +Check our [developer guide](doc/developer_guide/developer_guide.md#getting-the-openfasttrace-library) to learn how to use the OFT JAR as dependency in your own code with popular build tools. ## Installation @@ -135,6 +136,6 @@ If you want to run OFT in a CI build, you can use the OFT wrapper script [oftw.s ## Development -If you want to learn how to build OpenFastTrace, please check our [Developer Guide](doc/developer_guide.md). +If you want to learn how to build OpenFastTrace, please check our [Developer Guide](doc/developer_guide/developer_guide.md). You would like to contribute to OFT? Please check out our [Contributor Guide](CONTRIBUTING.md) to get started. diff --git a/_config.yml b/_config.yml new file mode 100644 index 000000000..898bf13e5 --- /dev/null +++ b/_config.yml @@ -0,0 +1,50 @@ +title: OpenFastTrace +description: Requirement tracing suite for Agile Development +source: doc +destination: _site + +remote_theme: just-the-docs/just-the-docs + +plugins: + - jekyll-remote-theme + - jekyll-seo-tag + - jekyll-include-cache + +# Site settings +url: "https://openfasttrace.itsallcode.org" +baseurl: "" + +# Navigation bar logo +logo: "/images/openfasttrace_logo.svg" + +# Aux links for the sidebar +aux_links: + "OpenFastTrace on GitHub": + - https://github.com/itsallcode/openfasttrace + +# Heading anchor links +heading_anchors: true + +# Search configuration +search_enabled: true +search: + tokenizer_separator: /[\s/]+/ + rel_prefix: true + +# Footer content +footer_content: "" + +# Color scheme +color_scheme: light + +# Exclude list +exclude: + - vendor + - .bundle + - .jekyll-cache + - .jekyll-metadata + - Gemfile + - Gemfile.lock + +include: + - CNAME diff --git a/doc/CNAME b/doc/CNAME new file mode 100644 index 000000000..e4d4f45ed --- /dev/null +++ b/doc/CNAME @@ -0,0 +1 @@ +openfasttrace.itsallcode.org diff --git a/doc/OFT-Ideas-and-Proposals.pdf b/doc/OFT-Ideas-and-Proposals.pdf deleted file mode 100644 index f556eeaa5..000000000 Binary files a/doc/OFT-Ideas-and-Proposals.pdf and /dev/null differ diff --git a/doc/about_us.md b/doc/about_us.md index ad02dd0e1..b48605d18 100644 --- a/doc/about_us.md +++ b/doc/about_us.md @@ -1,3 +1,8 @@ +--- +layout: default +title: About us +nav_order: 7 +--- # About us diff --git a/doc/changes/changes.md b/doc/changes/changes.md index 46a751710..551a5157e 100644 --- a/doc/changes/changes.md +++ b/doc/changes/changes.md @@ -1,3 +1,9 @@ +--- +layout: default +title: Changelog +nav_order: 8 +--- + # Changes * [4.10.0](changes_4.10.0.md) diff --git a/doc/changes/changes_4.0.1.md b/doc/changes/changes_4.0.1.md index f0e7d6827..a170b74a7 100644 --- a/doc/changes/changes_4.0.1.md +++ b/doc/changes/changes_4.0.1.md @@ -4,7 +4,7 @@ Code name: Allow numbers after dots in specification item names ## Summary -This release allows using specification item names with dots `.` followed by numbers, e.g. `req~SR.AB.1.1.1~1`. We also updated the relevant [section in the user guide](../user_guide/user_guide.md#specification-item-name). Thanks to [@RobertZickler](https://github.com/RobertZickler) for reporting this! +This release allows using specification item names with dots `.` followed by numbers, e.g. `req~SR.AB.1.1.1~1`. We also updated the relevant [section in the user guide](../user_guide/introduction/concepts_and_terms.md#specification-item-name). Thanks to [@RobertZickler](https://github.com/RobertZickler) for reporting this! ## Bugfixes diff --git a/doc/changes/changes_4.1.0.md b/doc/changes/changes_4.1.0.md index eee32d73d..0297bebd3 100644 --- a/doc/changes/changes_4.1.0.md +++ b/doc/changes/changes_4.1.0.md @@ -7,7 +7,7 @@ Code name: Third-party plugins This release adds support for loading third-party plugins from external JAR files. See the documentation for details: * [Installation](../plugins.md) -* [Plugin developer guide](../plugin_developer_guide.md) +* [Plugin developer guide](../developer_guide/plugin_developer_guide.md) The release also adds command line option `--log-level` that allows configuring the log level. Possible values are `OFF`, `SEVERE`, `WARNING`, `INFO`, `CONFIG`, `FINE`, `FINER`, `FINEST`, `ALL`. The default log level is `WARNING`. diff --git a/doc/developer_guide.md b/doc/developer_guide/developer_guide.md similarity index 96% rename from doc/developer_guide.md rename to doc/developer_guide/developer_guide.md index 2aa033eb3..47761c2b6 100644 --- a/doc/developer_guide.md +++ b/doc/developer_guide/developer_guide.md @@ -1,14 +1,21 @@ +--- +layout: default +title: Developer Guide +nav_order: 3 +has_children: true +--- + # OpenFastTrace Developer Guide This document contains technical information for developers contributing to OpenFastTrace (short OFT). -If you want to know more about how to contribute to OFT, please check out our [Contributor Guide](../CONTRIBUTING.md). +If you want to know more about how to contribute to OFT, please check out our [Contributor Guide](../../CONTRIBUTING.md). ## Getting the OpenFastTrace Library ### Getting OFT via Maven -To use OpenFastTrace as a dependency in your [Maven](https://maven.apache.org) project add this to your `pom.xml`: +To use OpenFastTrace as a dependency in your [Maven](https://maven.apache.org) project add this to your `../../pom.xml`: ```xml @@ -122,7 +129,7 @@ Build OFT: mvn -T 1C package -DskipTests ``` -This will build the executable JAR including all modules at `product/target/openfasttrace-$VERSION.jar`. +This will build the executable JAR including all modules at `product/target/openfasttrace-.jar`. (Please check for the latest version in the releases if you are downloading a pre-built JAR.) #### Specify Java Version @@ -189,7 +196,7 @@ Import as a Maven project using *"File" → "Import..." → "Maven" → All subprojects come with formatter and save actions configuration for Eclipse. -If you use a different IDE like IntelliJ, please import the formatter configuration [itsallcode_formatter.xml](itsallcode_formatter.xml). +If you use a different IDE like IntelliJ, please import the formatter configuration [itsallcode_formatter.xml](../itsallcode_formatter.xml). ## Configure Logging @@ -262,9 +269,9 @@ mvn package 2. Create a new "prepare-release" branch. 3. Update the version in * `openfasttrace-parent/pom.xml` (`revision` property) - * `README.md` + * `../../README.md` * `doc/developer_guide.md` -4. Add changes in a new version to `doc/changes/changes.md` and `doc/changes/changes_$VERSION.md` and update the release date. +4. Add changes in a new version to `../changes/changes.md` and `doc/changes/changes_$VERSION.md` and update the release date. 5. Commit and push changes. 6. Create a new pull request, have it reviewed and merged to `main`. diff --git a/doc/plugin_developer_guide.md b/doc/developer_guide/plugin_developer_guide.md similarity index 95% rename from doc/plugin_developer_guide.md rename to doc/developer_guide/plugin_developer_guide.md index 3faddabf0..bc2642564 100644 --- a/doc/plugin_developer_guide.md +++ b/doc/developer_guide/plugin_developer_guide.md @@ -1,6 +1,12 @@ +--- +layout: default +title: Plugin Developer Guide +parent: Developer Guide +--- + # Plugin Developer Guide -This guide describes how to develop [plugins](plugins.md) for OpenFastTrace (OFT). +This guide describes how to develop [plugins](../plugins.md) for OpenFastTrace (OFT). ## Initial Setup diff --git a/doc/images/openfasttrace_logo.svg b/doc/images/openfasttrace_logo.svg new file mode 100644 index 000000000..824b26698 --- /dev/null +++ b/doc/images/openfasttrace_logo.svg @@ -0,0 +1,93 @@ + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + diff --git a/doc/index.md b/doc/index.md new file mode 100644 index 000000000..ddec60294 --- /dev/null +++ b/doc/index.md @@ -0,0 +1,45 @@ +--- +layout: default +title: Home +nav_order: 1 +permalink: / +description: OpenFastTrace is a requirement tracing suite for Agile Development. +--- + +# OFT logo OpenFastTrace + +## What is OpenFastTrace? + +OpenFastTrace (short OFT) is a requirement tracing suite. Requirement tracing keeps track of whether you actually implemented everything you planned to in your specifications. It also identifies obsolete parts of your product and helps you to get rid of them. + +You can learn more about requirement tracing and how to use OpenFastTrace in the [user guide](user_guide/user_guide.md). + +Below you see a screenshot of an HTML tracing report where OFT traces itself. You see a summary followed by a detail view of the traced requirements. + +OFT HTML tracing report + +## Quick Links + +* [๐Ÿ“– User Guide](user_guide/user_guide.md) +* [๐Ÿฆฎ Developer Guide](developer_guide/developer_guide.md) +* [๐Ÿ“œ Specification](spec/index.md) +* [๐Ÿ”Œ Extending OpenFastTrace With Plugins](plugins.md) +* [โž• Changelog](changes/changes.md) +* [โ„น๏ธ About us](about_us.md) + +## Project Information + +* [๐Ÿ’ป GitHub Repository](https://github.com/itsallcode/openfasttrace) +* [๐Ÿ“ฆ Maven Central](https://search.maven.org/search?q=g:org.itsallcode.openfasttrace%20a:openfasttrace) +* [๐Ÿ“ฝ๏ธ Introduction Video](https://www.youtube.com/watch?v=tlzMT6RaVWA) +* [๐Ÿ›— Elevator Pitch](https://github.com/itsallcode/openfasttrace-demo/tree/main?tab=readme-ov-file#elevator-pitch) +* [๐Ÿ“ข Blog](https://blog.itsallcode.org/) +* [๐Ÿ—จ๏ธ Discussion Board](https://github.com/itsallcode/openfasttrace/discussions) + +## Tools and Resources + +* [๐Ÿ“š Terminology](terminology.md) +* [๐Ÿ›  IntelliJ Plugin](https://github.com/itsallcode/openfasttrace-intellij-plugin) +* [๐Ÿ˜ OpenFastTrace@mastodon.social](https://mastodon.social/@OpenFastTrace) +* [๐Ÿ›ก๏ธ Security Policy](https://github.com/itsallcode/openfasttrace/blob/main/SECURITY.md) +* [๐Ÿ’ฒ Command Line Usage](https://github.com/itsallcode/openfasttrace/blob/main/core/src/main/resources/usage.txt) diff --git a/doc/plugins.md b/doc/plugins.md index 054b3bc19..d83477734 100644 --- a/doc/plugins.md +++ b/doc/plugins.md @@ -1,15 +1,25 @@ +--- +layout: default +title: Plugins +nav_order: 6 +--- + # Extending OpenFastTrace With Plugins -Version 4.1.0 adds support for extending OFT with third-party plugins. +OpenFastTrace (OFT) is designed to be extensible. You can add new importers, exporters, and reporters by using plugins. + +## Installation + +OFT automatically loads plugins from JAR files located in a predefined location at startup. -## Installing Plugins +To install a plugin, copy the plugin's JAR file to the following directory depending on your operating system: -You install a plugin by copying its JAR files to `$HOME/.oft/plugins//*.jar`. OFT will automatically load plugins from this location. To check which plugins are available, start OFT with command line argument `--log-level INFO`. This will log all available plugins and their location. +* **Linux**: `$HOME/.oft/plugins/` +* **Windows**: `%APPDATA%/oft/plugins/` +* **macOS**: `$HOME/Library/Application Support/oft/plugins/` -## Available Plugins +After copying the JAR file, the plugin will be available the next time you run OFT. -Currently no third-party plugins are available. If you want to add a new plugin, please create a [GitHub issue](https://github.com/itsallcode/openfasttrace/issues/new?assignees=&labels=&projects=&template=New_plugin.md). +## Developing Plugins -| Plugin Name | Plugin Type | Description | -|-------------|-------------|-------------| -| N/A | N/A | Currently, no third-party plugins are available for OpenFastTrace. | +If you want to develop your own plugins for OFT, please refer to the [Plugin Developer Guide](developer_guide/plugin_developer_guide.md). diff --git a/doc/spec/design.md b/doc/spec/design.md index d440a79b5..fb134d2e9 100644 --- a/doc/spec/design.md +++ b/doc/spec/design.md @@ -1,7 +1,9 @@ - - - OpenFastTrace Design - +--- +layout: default +title: Design +nav_order: 2 +parent: Specification +--- # Introduction @@ -12,7 +14,7 @@ This document's structure is derived from the "[arc42][bib.arc42]" architectural If you build your own modifications based on this document, please keep the attrbiutions. ## Terminology -The terminology from the [system requirement specification][bib.srs] applies. +The terminology from the [central terminology document][bib.terminology] applies. ## Conventions @@ -105,7 +107,7 @@ The `importer/tag-importer-common` module provides the reusable line scanning an The tag importer remains responsible for selecting its input files and creating the shared parser. Parsing implementation classes remain encapsulated in the shared module so that future importers can reuse the same coverage-tag semantics without depending on tag-importer internals. ## Import Event Listener -Importers emit events if they find parts of a [specification item](#specification-item) in the artifact they are importing. +Importers emit events if they find parts of a [specification item](../terminology.md#specification-item) in the artifact they are importing. ### Specification List Builder The specification list builder is an import event listener that creates a list of specification items from import events. @@ -155,7 +157,7 @@ Needs: impl, utest The command line interpreter (CLI) takes parameters given to OFT and parses them. It is responsible for making sense of the parameter contents and issuing help and error messages about the command line syntax. ## Linker -The linker is responsible for turning the imported [specification items](#specification-item) collected by the [importers](#importers) into [linked specification items](#linked-specification-item). +The linker is responsible for turning the imported [specification items](../terminology.md#specification-item) collected by the [importers](#importers) into [linked specification items](#linked-specification-item). ## Tracer The tracer consumes the list of [linked specification items](#linked-specification-item) and evaluates the link status for each link. @@ -166,7 +168,7 @@ The reporter consumes the link status list and the specification item list and g API users select reporters via their name as strings. This allows plugging in custom reporters in a loosely coupled fashion. ## Exporters -The exporter transforms the internal representation of [specification items](#specification-item) into the desired target format (e.g. Markdown). +The exporter transforms the internal representation of [specification items](../terminology.md#specification-item) into the desired target format (e.g. Markdown). API users select exporters via their name as strings. @@ -227,7 +229,7 @@ Needs: impl, itest ## Import -Depending on the source format, a variety of [importers](#importers) takes care of reading the input [specification items](#specification-item). Each importer emits events which an [import event listener](#import-event-listener) consumes. +Depending on the source format, a variety of [importers](#importers) takes care of reading the input [specification items](../terminology.md#specification-item). Each importer emits events which an [import event listener](#import-event-listener) consumes. The listener handles Common parts of the import like filtering out unnecessary items or attributes. @@ -467,7 +469,7 @@ Needs: impl, utest The [linker](#linker) component iterates over all needed artifact types of all specification items and determines if and which coverage exists for each. Comment: -Note that the linker only takes care of swallow coverage. [Deep coverage](#deep-coverage) is determined by the [tracer](#tracer) component. +Note that the linker only takes care of swallow coverage. [Deep coverage](../terminology.md#deep-coverage) is determined by the [tracer](#tracer) component. Covers: @@ -527,7 +529,7 @@ Needs: impl, utest ### Duplicate Items `dsn~tracing.tracing.duplicate-items~1` -The [tracer](#tracer) marks a [specification item](#specification-item) as a _duplicate_ if other items with an identical [specification item ID](#specification-item-id) exist. +The [tracer](#tracer) marks a [specification item](../terminology.md#specification-item) as a _duplicate_ if other items with an identical [specification item ID](../terminology.md#specification-item-id) exist. Covers: @@ -538,7 +540,7 @@ Needs: impl, utest ### Defect Items `dsn~tracing.defect-items~2` -The [tracer](#tracer) marks a [specification item](#specification-item) as _defect_ if the following criteria apply to the item +The [tracer](#tracer) marks a [specification item](../terminology.md#specification-item) as _defect_ if the following criteria apply to the item has duplicates or (not rejected @@ -556,7 +558,7 @@ Needs: impl, utest ### Transitive Defect `dsn~tracing.transitive-defect~1` -The [tracer](#tracer) identifies a [specification item](#specification-item) as having a _transitive defect_ if it is a [defect item](#defect-items) but none of the direct defect criteria apply. +The [tracer](#tracer) identifies a [specification item](../terminology.md#specification-item) as having a _transitive defect_ if it is a [defect item](#defect-items) but none of the direct defect criteria apply. A transitive defect occurs when a specification item itself fulfills all direct coverage requirements, but at least one of the items it covers (directly or indirectly) is a defect item. @@ -796,7 +798,7 @@ Needs: impl, utest #### HTML Report Transitive Defect Mark `dsn~reporting.html.transitive-defect-mark~1` -The HTML report renders the transitive defect mark (โŽ) for items that have a [transitive defect](#transitive-defect). +The HTML report renders the transitive defect mark (โŽ) for items that have a [transitive defect](../terminology.md#transitive-defect). Covers: @@ -893,7 +895,7 @@ Needs: impl, utest #### Linked Specification Item `dsn~linked-specification-item~1` -A `LinkedSpecificationItem` is a container for a [SpecificationItem](#specification-item) that is enriched with references to other `LinkedSpecificationItem`s. +A `LinkedSpecificationItem` is a container for a [SpecificationItem](../terminology.md#specification-item) that is enriched with references to other `LinkedSpecificationItem`s. Rationale: This allows navigating between specification items. @@ -1473,13 +1475,15 @@ Clean-up in every importer individually. That was the case up to and including O The following documents or are referenced in this specification. [bib.srs]: system_requirements.md "OpenFastTrace System Requirement Specification" +[bib.terminology]: terminology.md "OpenFastTrace Terminology" [bib.abnf]: ftp://ftp.rfc-editor.org/in-notes/std/std68.txt "Augmented BNF for Syntax Specifications: ABNF" [bib.arc42]: http://arc42.org ## Specifications * [System Requirement Specification OpenFastTrace][bib.srs], Sebastian Bรคr -* [Augmented BNF for Syntax Specifications: ABNF][bib.abnf] , D. Crocker, P. Overell, January 2008 +* [OpenFastTrace Terminology][bib.terminology] +* [Augmented BNF for Syntax Specifications: ABNF][bib.abnf], D. Crocker, P. Overell, January 2008 ## Web Sites diff --git a/doc/spec/index.md b/doc/spec/index.md new file mode 100644 index 000000000..9fd20bc5c --- /dev/null +++ b/doc/spec/index.md @@ -0,0 +1,13 @@ +--- +layout: default +title: Specification +nav_order: 4 +has_children: true +--- + +# OpenFastTrace Specification + +This section contains the formal specifications for OpenFastTrace. + +* [System Requirements](system_requirements.md) +* [Design](design.md) diff --git a/doc/spec/oft_spec.css b/doc/spec/oft_spec.css deleted file mode 100644 index fe852b57c..000000000 --- a/doc/spec/oft_spec.css +++ /dev/null @@ -1,89 +0,0 @@ -@CHARSET "UTF-8"; - -body { - counter-reset: section; - font-family: Helvetica, arial, sans-serif; - font-size: 14px; - line-height: 1.5; - padding-top: 10px; - padding-bottom: 10px; - padding-left: 30px; - padding-right: 30px; - background-color: white; - color: #333; -} - -h1, h2, h3, h4 { - border-style: none; - text-decoration-line: none; -} - -h1:before { - counter-increment: section; - content: counter(section) " "; -} - -h1 { - counter-reset: sub-section; - font-size: 20px; - border-bottom: 1px solid lightgrey; -} - -h2:before { - counter-increment: sub-section; - content: counter(section) "." counter(sub-section) " "; -} - -h2 { - counter-reset: composite; - font-size: 18px; -} - -h3:before { - counter-increment: composite; - content: counter(section) "." counter(sub-section) "." - counter(composite) " "; -} - -h3 { - counter-reset: detail; - font-size: 16px; -} - -h4:before { - counter-increment: detail; - content: counter(section) "." counter(sub-section) "." - counter(composite) "." counter(detail) " "; -} - -h4 { - font-size: 14px; -} - -li { - list-style-type: square; -} - -p { - width: 100%; -} - -h1 + p > code:first-of-type, -h2 + p > code:first-of-type, -h3 + p > code:first-of-type, -h4 + p > code:first-of-type, -h5 + p > code:first-of-type, -h6 + p > code:first-of-type { - display: block; - font-size: 12px; - color: grey; - border-bottom: 1px dotted lightgrey; - text-align: right; - width: 100%; - position: relative; - top: -2.5em; -} - -img[alt=oft-logo] { - width: 250px; -} \ No newline at end of file diff --git a/doc/spec/system_requirements.md b/doc/spec/system_requirements.md index 17203e497..6d96d0d3b 100644 --- a/doc/spec/system_requirements.md +++ b/doc/spec/system_requirements.md @@ -1,7 +1,9 @@ - - - System Requirement Specification OpenFastTrace - +--- +layout: default +title: System Requirements +nav_order: 1 +parent: Specification +--- # System Requirement Specification OpenFastTrace @@ -26,36 +28,9 @@ It looks strange first that "useful" needs to be spelled out as a goal. The reas OFT aims to help developers independently of their platform. I should not matter if you are developing on Linux, a Mac, BSD, Windows. Also it should not matter which programming language or development environment you are using. OFT aims to be portable and provide interfaces that allow integration into your existing toolchain. -### Terms and Abbreviations +### Terminology -The following list gives you an overview of terms and abbreviations commonly used in OFT documents. - -* Artifact: a container for specification items -* Artifact type: the role of an artifact in a specification hierarchy -* Coverage: Specification items covering other specification items -* Coverage provider: a specification item that provides coverage -* Coverage requester: a specification item that needs coverage -* OFT: OpenFastTrace (this project) -* ReqM2: A requirement tracing suite -* Specification item: holds either a requirement or coverage -* Specification artifact: a data source containing specification items (e.g. file, ticket system, - database) - -In the following subsections central terms are explained in more detail. - -#### Specification Items - -In OFT requirements and artifacts covering them are represented by [specification items](#specification-item). Each item is a container for attributes of requirements and covering artifacts like the name, artifact type and the location where OFT found them. - -A specification item can also contain information about its relationships to other specification items. For more details about those relationships check [section "tracing"](#tracing). - -#### Coverage - -Coverage is a measure of how well the tracing result matches the required relations between specification items. - -Full coverage is what a project aims to achieve: all required relations between specification items exist. - -An item is undercovered if at least one of the required relations is missing. It is overcovered if at least one relation exists that is not required. +OpenFastTrace uses unified terminology for all documents. Please refer to the [central terminology document](../terminology.md) for definitions of terms like [specification item](../terminology.md#specification-item), [coverage](../terminology.md#coverage), and [artifact](../terminology.md#artifact). ## Features @@ -973,7 +948,7 @@ The return value of the OFT executable reflects the overall tracing result. Covers: -* [feat~requirement-tracing~1](#requirement-tracing~1 +* [feat~requirement-tracing~1](#requirement-tracing) Needs: dsn diff --git a/doc/terminology.md b/doc/terminology.md new file mode 100644 index 000000000..1add93783 --- /dev/null +++ b/doc/terminology.md @@ -0,0 +1,115 @@ +--- +layout: default +title: Terminology +nav_order: 5 +--- + +# OpenFastTrace Terminology + +## A + +### Artifact +A source or container for [specification items](#specification-item) (e.g., file, database). + +### Artifact Type +Classification of an artifact's role in the trace hierarchy (e.g., `feat`, `req`, `dsn`). + +## C + +### Coverage +Relationship between a [specification item](#specification-item) and the items that detail, implement, or verify it. + +### Coverage Link +A directed relationship between a requester and a provider of coverage. + +### Coverage Provider +A [specification item](#specification-item) that fulfills a coverage requirement of another item. + +### Coverage Requester +A [specification item](#specification-item) that explicitly demands coverage by specific [artifact types](#artifact-type). + +## D + +### Deep Coverage +Full coverage of a [specification item](#specification-item) including all its transitive providers down to [terminating specification items](#terminating-specification-item). + +## F + +### Forwarding +Shorthand for delegating coverage responsibility to other [artifact types](#artifact-type) without adding new design decisions. + +### Full Coverage +Condition where all required coverage links are present and valid for a given scope. + +## I + +### Informative Passage +Content in a specification document that provides context without containing [specification items](#specification-item). + +## N + +### Normative Passage +Content that defines [specification items](#specification-item) or coverage links. + +## O + +### OpenFastTrace +The requirement tracing tool suite. + +## OFT + +See [OpenFastTrace](#openfasttrace) + +### Overcovered +A condition where a [specification item](#specification-item) has more coverage links than required. + +## R + +### Rationale +Optional part of a [specification item](#specification-item) explaining the reasoning behind a requirement. + +### ReqM2 +A legacy requirement tracing format supported for import. + +## S + +### Specification Artifact +See [Artifact](#artifact) + +### Specification Item +The atomic unit of a specification, representing a requirement, design decision, or coverage marker. + +### Specification Item ID +Unique identifier of a [specification item](#specification-item), consisting of [artifact type](#artifact-type), [name](#specification-item-name), and [revision](#specification-item-revision). + +### Specification Item Name +The unique name part of a [specification item ID](#specification-item-id). + +### Specification Item Revision +Number in the [specification item ID](#specification-item-id) used to invalidate coverage when an item's meaning changes. + +## SRS + +See [System Requirement Specification](#system-requirement-specification) + +### Status +Defines the maturity level of a [specification item](#specification-item): `draft`, `proposed`, `approved` or `rejected` . + +### System Requirement Specification +A document describing the requirements of a system. + +## T + +### Tag +Label for categorizing [specification items](#specification-item), used for filtering or work distribution. + +### Terminating Specification Item +A [specification item](#specification-item) that does not require further coverage (e.g., code, tests). + +### Transitive Defect +Coverage gap caused by an undercovered provider in the trace chain. + +## U + +### Undercovered +A condition where one or more required coverage links for a [specification item](#specification-item) are missing. diff --git a/doc/user_guide/installation/installation.md b/doc/user_guide/installation/installation.md new file mode 100644 index 000000000..3c0a50823 --- /dev/null +++ b/doc/user_guide/installation/installation.md @@ -0,0 +1,29 @@ +--- +layout: default +title: Installation +parent: User Guide +has_children: true +--- + +## Installation + +OpenFastTrace (OFT) can be used in two primary ways: integrated into your build environment or as a standalone tool for interactive use. + +### Build Plugins vs. Standalone Installation + +Before installing OFT, it is important to understand which type of installation you need: + +* **Build Environment Plugins**: If you want to integrate requirement tracing into your automated build pipeline (e.g., using Maven or Gradle), you should use the respective build plugins. These plugins are managed by the build system and typically do not require a manual installation of the OFT executable on your machine. See [Build Integration](../reference/build_integration.md) for more details. +* **Standalone Installation**: If you want to use OFT interactively from the command line, run ad-hoc traces, or use it in custom scripts, you should install the standalone CLI tool. This is what the following sections describe. + +### Standalone Installation by Operating System + +Depending on your operating system, there are different ways to install OpenFastTrace. Please choose the guide for your system: + +* **[Linux Installation](linux.md)** (Debian, Ubuntu, and others) +* **[macOS Installation](macos.md)** +* **[Windows Installation](windows.md)** + +--- + +โ† [Concepts and Terms](../introduction/concepts_and_terms.md) | โ†‘ [User Guide](../user_guide.md) | [Linux Installation](linux.md) โ†’ diff --git a/doc/user_guide/installation/linux.md b/doc/user_guide/installation/linux.md new file mode 100644 index 000000000..c02aa3f27 --- /dev/null +++ b/doc/user_guide/installation/linux.md @@ -0,0 +1,56 @@ +## Linux Installation + +There are several ways to install OpenFastTrace on Linux, depending on your distribution and preference. + +### Package Manager (APT - Debian, Ubuntu, etc.) + +For Debian-based systems, we provide an APT repository. This is the recommended way to keep OFT up to date. + +1. Follow the instructions at the [itsallcode-apt-repository](https://github.com/itsallcode/itsallcode-apt-repository) to add the repository to your system. +2. Install OpenFastTrace using: + ```bash + sudo apt update + sudo apt install openfasttrace + ``` + +### Homebrew (Linuxbrew) + +If you use Homebrew on Linux, you can install OpenFastTrace directly: + +```bash +brew install openfasttrace +``` + +### Manual Installation + +If you prefer a manual setup, you can use the executable JAR file directly. + +#### 1. Install Java + +OpenFastTrace requires **Java 17 or newer**. On Linux, you can usually install it via your package manager: + +* **Debian/Ubuntu**: `sudo apt install default-jre` or `sudo apt install openjdk-17-jre` +* **Fedora/RHEL**: `sudo dnf install java-17-openjdk` +* **Arch Linux**: `sudo pacman -S jre17-openjdk` + +#### 2. Download OFT + +Download the `openfasttrace-.jar` from the [GitHub Releases](https://github.com/itsallcode/openfasttrace/releases) page. Please check for the latest available version there. + +#### 3. Run OFT + +You can now run OFT using: +```bash +java -jar path/to/openfasttrace-.jar --help +``` + +#### 4. Creating a command alias (Optional) + +To make it easier to run, add an alias to your `.bashrc` or `.zshrc`: +```bash +alias oft='java -jar /path/to/openfasttrace-.jar' +``` + +--- + +โ† [Installation](installation.md) | โ†‘ [Installation](installation.md) | [macOS Installation](macos.md) โ†’ diff --git a/doc/user_guide/installation/macos.md b/doc/user_guide/installation/macos.md new file mode 100644 index 000000000..afec20193 --- /dev/null +++ b/doc/user_guide/installation/macos.md @@ -0,0 +1,44 @@ +## macOS Installation + +OpenFastTrace can be installed on macOS using Homebrew or manually via a JAR file. + +### Homebrew + +If you use Homebrew, you can install OpenFastTrace directly: + +```bash +brew install openfasttrace +``` + +### Manual Installation + +If you prefer a manual setup, you can use the executable JAR file directly. + +#### 1. Install Java + +OpenFastTrace requires **Java 17 or newer**. On macOS, you can install it using Homebrew or download it from a provider like Adoptium. + +* **Homebrew**: `brew install openjdk@17` +* **Manual Download**: Visit [Adoptium (Temurin)](https://adoptium.net/) and download the macOS installer (.pkg or .dmg) for Java 17 or newer. + +#### 2. Download OFT + +Download the `openfasttrace-.jar` from the [GitHub Releases](https://github.com/itsallcode/openfasttrace/releases) page. Please check for the latest available version there. + +#### 3. Run OFT + +You can now run OFT using: +```bash +java -jar path/to/openfasttrace-.jar --help +``` + +#### 4. Creating a command alias (Optional) + +To make it easier to run, add an alias to your `.zshrc` (or `.bash_profile`): +```bash +alias oft='java -jar /path/to/openfasttrace-.jar' +``` + +--- + +โ† [Linux Installation](linux.md) | โ†‘ [Installation](installation.md) | [Windows Installation](windows.md) โ†’ diff --git a/doc/user_guide/installation/windows.md b/doc/user_guide/installation/windows.md new file mode 100644 index 000000000..2deb88988 --- /dev/null +++ b/doc/user_guide/installation/windows.md @@ -0,0 +1,36 @@ +## Windows Installation + +On Windows, OpenFastTrace is typically run manually via the JAR file. + +### Manual Installation + +#### 1. Install Java + +OpenFastTrace requires **Java 17 or newer**. On Windows, you can install it using `winget` or download an installer. + +* **winget**: `winget install eclipse.temurin.17.jre` +* **Manual Download**: Visit [Adoptium (Temurin)](https://adoptium.net/) and download the Windows MSI installer for Java 17 or newer. + +#### 2. Download OFT + +Download the `openfasttrace-.jar` from the [GitHub Releases](https://github.com/itsallcode/openfasttrace/releases) page. Please check for the latest available version there. + +#### 3. Run OFT + +You can now run OFT via PowerShell or Command Prompt: +```powershell +java -jar C:\path\to\openfasttrace-.jar --help +``` + +#### 4. Creating a command alias (Optional) + +To make it easier to run, create a batch file named `oft.bat` in a directory that is in your system `PATH` (e.g., `C:\Windows\System32` or a custom tools folder): + +```batch +@echo off +java -jar "C:\path\to\openfasttrace-.jar" %* +``` + +--- + +โ† [macOS Installation](macos.md) | โ†‘ [Installation](installation.md) | [Use Cases](../use_cases/use_cases.md) โ†’ diff --git a/doc/user_guide/introduction/concepts_and_terms.md b/doc/user_guide/introduction/concepts_and_terms.md new file mode 100644 index 000000000..71f7a3365 --- /dev/null +++ b/doc/user_guide/introduction/concepts_and_terms.md @@ -0,0 +1,60 @@ +### Concepts and Terms + +OpenFastTrace uses unified terminology for all documents. Please refer to the [central terminology document](../../terminology.md) for core definitions of terms like [specification item](../../terminology.md#specification-item), [coverage](../../terminology.md#coverage), and [artifact](../../terminology.md#artifact). + +The following sections provide detailed information on the parts of a [specification item ID](../../terminology.md#specification-item-id). + +#### Specification Item Artifact Type + +The artifact type serves two purposes: + +1. identifying the source document type +2. identifying the position in the tracing hierarchy + +Artifact types are represented by character strings consisting out of ASCII letters. No other characters are allowed. + +While not enforced by OFT, the following strings are well-established: + +* `feat` - high-level feature +* `req` - user requirement +* `arch` - architectural requirement +* `dsn` - design requirement +* `impl` - implementation +* `utest` - unit test +* `itest` - integration test +* `stest` - system test +* `uman` - user manual +* `oman` - operation manual + +If you don't distinguish between architectural and detailed design, we recommend using `dsn` for both. The OFT specification, for example, does it that way. + +How many types you introduce, how you name and stack them is up to you. When we designed OFT, we were clear about the fact that we would not be able to cover all possible artifact types one could imagine, so we did not hardcode them into OFT. + +#### Specification Item Name + +The name part of the ID must be a character string consisting of Unicode letters and/or numbers separated by underscore (`_`), hyphen (`-`) or dot (`.`). Whitespaces are not allowed. + +* Names must start with a unicode letter +* Consecutive dots `.` are not allowed + +We recommend using a dot `.` to create a hierarchy of items: + + exporter.html5.folding + exporter.html5.colors + exporter.csv.column_names + +#### Specification Item Revision + +The revision number of a specification item is a positive integer number that can be started at zero but by convention usually is started at one. + +The revision is intended to obsolete existing coverage links in case the content of a specification item semantically changed. Incrementing the revision voids all existing links to this item so that authors linking to the item know they have to check for changes and adapt the covering items. + +Examples: + +If you change a requirement that lists all browsers that an HTML export needs to be compatible with, you made a semantic change and should raise the revision number. + +If, on the other hand, you only added a missing period at the end of a sentence, the requirement content did not really change and there is no need to invalidate existing coverage. + +--- + +โ† [Why do I Need Requirement Tracing?](why_do_i_need_requirement_tracing.md) | โ†‘ [Introduction](introduction.md) | [Installation](../installation/installation.md) โ†’ diff --git a/doc/user_guide/introduction/introduction.md b/doc/user_guide/introduction/introduction.md new file mode 100644 index 000000000..3b06eb367 --- /dev/null +++ b/doc/user_guide/introduction/introduction.md @@ -0,0 +1,12 @@ +--- +layout: default +title: Introduction +parent: User Guide +has_children: true +--- + +## Introduction + +--- + +โ†‘ [User Guide](../user_guide.md) | [Who Should Read This Document?](who_should_read_this_document.md) โ†’ diff --git a/doc/user_guide/introduction/what_is_requirement_tracing.md b/doc/user_guide/introduction/what_is_requirement_tracing.md new file mode 100644 index 000000000..39a5f42dd --- /dev/null +++ b/doc/user_guide/introduction/what_is_requirement_tracing.md @@ -0,0 +1,19 @@ +### What is Requirement Tracing? + +OpenFastTrace is a requirement tracing suite. Requirement tracing helps you to keep track of whether you actually implemented everything you planned to in your specifications. It also identifies obsolete parts of your product and helps you to get rid of them. + +The foundation of all requirement tracing is links between documents, implementation, test, reports and whatever other artifacts your product consists of. + +Let's assume you compiled a list of five main features your users asked for. They are very coarse but provide a nice overview of what your project is expected to achieve. Next you decide to write a few dozen user stories to flesh out the details of what your users want. + +In order not to forget anything important, you create a link from each user story to the corresponding feature. + +After you are done you want to make sure everything is in order. Instead of checking all the links by hand, you let OFT check if every feature is covered in at least one user story. + +OFT comes back with a result that one of your features is not covered. You realize that you indeed forgot that one, write two new user stories and link them to the so far uncovered feature. This time OFT comes back with an assuring "OK". + +Step-by-step you repeat this pattern for your design document and all resulting artifacts. + +--- + +โ† [Who Should Read This Document?](who_should_read_this_document.md) | โ†‘ [Introduction](introduction.md) | [Why do I Need Requirement Tracing?](why_do_i_need_requirement_tracing.md) โ†’ diff --git a/doc/user_guide/introduction/who_should_read_this_document.md b/doc/user_guide/introduction/who_should_read_this_document.md new file mode 100644 index 000000000..6772debd6 --- /dev/null +++ b/doc/user_guide/introduction/who_should_read_this_document.md @@ -0,0 +1,24 @@ +### Who Should Read This Document? + +This document is mainly targeted at users wanting to learn how to use OFT for authoring requirement specifications, tracing requirement coverage and converting between requirement formats. + +In software projects those users are typically: + +* Technical writers +* Requirement engineers +* Software developers +* Quality engineers + +For this class of users all sections are of interest. + +The document is also helpful for people who just want to get an insight on what OFT is good for and the ideas behind it like: + +* Project managers +* IT Support personnel +* People responsible for picking tools (who we recommend should be users too) + +Of course, requirement engineering and tracing are useful outside the software domains too. + +--- + +โ† [Introduction](introduction.md) | โ†‘ [Introduction](introduction.md) | [What is Requirement Tracing?](what_is_requirement_tracing.md) โ†’ diff --git a/doc/user_guide/introduction/why_do_i_need_requirement_tracing.md b/doc/user_guide/introduction/why_do_i_need_requirement_tracing.md new file mode 100644 index 000000000..379cd1e30 --- /dev/null +++ b/doc/user_guide/introduction/why_do_i_need_requirement_tracing.md @@ -0,0 +1,12 @@ +### Why do I Need Requirement Tracing? + +Requirement tracing is a safety net for non-trivial software projects: + +* protects you from forgetting planned parts of your product +* finds orphaned code, documents and resources +* helps you track progress towards milestones +* allows you to prove due diligence during quality audits and customer reviews + +--- + +โ† [What is Requirement Tracing?](what_is_requirement_tracing.md) | โ†‘ [Introduction](introduction.md) | [Concepts and Terms](concepts_and_terms.md) โ†’ diff --git a/doc/user_guide/oft_api/exit_codes.md b/doc/user_guide/oft_api/exit_codes.md new file mode 100644 index 000000000..6ec1e4e3d --- /dev/null +++ b/doc/user_guide/oft_api/exit_codes.md @@ -0,0 +1,11 @@ +### Exit Codes + +The OFT command line interface returns the following exit codes: + +* `0` on success +* `1` on OFT error +* `2` on command line error + +--- + +โ† [Using OFT From Java](using_oft_from_java.md) | โ†‘ [OFT API](oft_api.md) | [Tool Support](../tool_support/tool_support.md) โ†’ diff --git a/doc/user_guide/oft_api/oft_api.md b/doc/user_guide/oft_api/oft_api.md new file mode 100644 index 000000000..01dae3012 --- /dev/null +++ b/doc/user_guide/oft_api/oft_api.md @@ -0,0 +1,16 @@ +--- +layout: default +title: OFT API +parent: User Guide +has_children: true +--- + +## OFT API + +If you are a software developer planning to integrate OFT into one of your programs or scripts, you will probably want to use the OFT API. + +Below you find a few short examples of how to use the OFT API. For details check the Javadoc documentation of the interface [org.itsallcode.openfasttrace.core.Oft](../../../core/src/main/java/org/itsallcode/openfasttrace/core/Oft.java) in the source code. + +--- + +โ† [XML Tracing Report](../reference/xml_tracing_report.md) | โ†‘ [User Guide](../user_guide.md) | [Using OFT From Java](using_oft_from_java.md) โ†’ diff --git a/doc/user_guide/oft_api/using_oft_from_java.md b/doc/user_guide/oft_api/using_oft_from_java.md new file mode 100644 index 000000000..7a62d8062 --- /dev/null +++ b/doc/user_guide/oft_api/using_oft_from_java.md @@ -0,0 +1,122 @@ +### Using OFT From Java + +The Java interface uses the "fluent programming" paradigm to make the code more compact and easy to read. + +The steps that you need to program using the OFT API depend on whether you want to covert between requirement formats + + import -> export + +or run a report. + + import -> link -> trace -> report + +#### Converting File from Java + +The following example code use OFT as a converter that scans the current working directory recursively (default import setting) and exports the found artifacts with the standard settings to a ReqM2 file. + +```java +import org.itsallcode.openfasttrace.Oft; +import org.itsallcode.openfasttrace.core.SpecificationItem; +``` + +Select input paths and import specification items from there: + +```java +final Oft oft = Oft.create(); +final List items = oft.importItems(settings); +``` + +Export the items: + +```java +oft.exportToPath(items, Paths.get("/output/path/export.oreqm")); +``` + +#### Tracing and Reporting From Java + +The example below shows how to use OFT as a reporter. + +```java +import org.itsallcode.openfasttrace.Oft; +import org.itsallcode.openfasttrace.core.LinkedSpecificationItem; +import org.itsallcode.openfasttrace.core.SpecificationItem; +import org.itsallcode.openfasttrace.core.Trace; +``` + +The import is similar to the converter case, except this time we add an input path explicitly for the sake of demonstration: + +```java +final ImportSettings settings = ImportSettings // + .builder() // + .addInputs("/input/path") // + .build; +final Oft oft = Oft.create(); +final List items = oft.importItems(settings); +``` + +Now link the items together (i.e. make them navigable): + +```java +final List linkedItems = oft.link(items); +``` + +Run the tracer on the linked items: + +```java +final Trace trace = oft.trace(linkedItems); +``` + +Create a report from the trace: + +```java +oft.reportToStdOut(trace); +``` + +You can also use the trace results in your own code: + +```java +if (trace.hasNoDefects()) +{ + // ... do something +} +``` + +#### Reporting Formats + +There are various reporting formats for OFT and one can set it using the ReportSettings object. + +```java +ReportSettings reportSettings = ReportSettings.builder().outputFormat("html").build(); +``` + +The `ReportSettings` builder has other functions as well that allow you to set verbosity etc. + +OFT allows you to report directly to the standard output or to a file + +```java +// Reporting to a file +oft.reportToPath(trace, reportPath, reportSettings); +``` + +```java +// Reporting to stdout +oft.reportToStdOut(trace); +``` + +#### Configuring the Steps + +Import, export and report each have an overloaded variant that can be configured using the following classes + +* [org.itsallcode.openfasttrace.api.importer.ImportSettings](../../../api/src/main/java/org/itsallcode/openfasttrace/api/importer/ImportSettings.java) +* [org.itsallcode.openfasttrace.core.ExportSettings](../../../core/src/main/java/org/itsallcode/openfasttrace/core/ExportSettings.java) +* [org.itsallcode.openfasttrace.api.ReportSettings](../../../api/src/main/java/org/itsallcode/openfasttrace/api/ReportSettings.java) + +Each of those classes comes with a builder which is called like this: + +```java +ReportSettings settings = ReportSettings.builder().newline(Newline.UNIX).build(); +``` + +--- + +โ† [OFT API](oft_api.md) | โ†‘ [OFT API](oft_api.md) | [Exit Codes](exit_codes.md) โ†’ diff --git a/doc/user_guide/project_lifecycle.md b/doc/user_guide/product_lifecycle/product_lifecycle.md similarity index 83% rename from doc/user_guide/project_lifecycle.md rename to doc/user_guide/product_lifecycle/product_lifecycle.md index 2567c0eda..5a8ec8a7d 100644 --- a/doc/user_guide/project_lifecycle.md +++ b/doc/user_guide/product_lifecycle/product_lifecycle.md @@ -1,4 +1,10 @@ -# Project Lifecycle +--- +layout: default +title: Product Lifecycle +parent: User Guide +--- + +# Product Lifecycle This is a free and open-source project. Updates are publicly available and free of charge. @@ -37,12 +43,16 @@ Migrate to OFT's full coverage tags, and you can drop the per-directory tag-impo ## Security Updates -Users need to check the [changelog](../changes/changes.md) to stay informed about security updates. You need to install the provided security updates in a timely manner to keep your setup secure. This is also true for any dependencies of this software that do not come bundled. An example is the Java Runtime Environment. +Users need to check the [changelog](../../changes/changes.md) to stay informed about security updates. You need to install the provided security updates in a timely manner to keep your setup secure. This is also true for any dependencies of this software that do not come bundled. An example is the Java Runtime Environment. Itsallcode.org provides security updates until the EoL listed above. -Please refer to our [security policy](../../SECURITY.md) for details on coordinated vulnerability disclosure. +Please refer to our [security policy](../../../SECURITY.md) for details on coordinated vulnerability disclosure. ### Retaining Updates -Itsallcode.org distributes updates via GitHub releases. Even if the project should be archived, the releases remain accessible for download. Itsallcode.org will keep each security update accessible for at least 10 years. \ No newline at end of file +Itsallcode.org distributes updates via GitHub releases. Even if the project should be archived, the releases remain accessible for download. Itsallcode.org will keep each security update accessible for at least 10 years. + +--- + +โ† [Templates for IDEs](../tool_support/templates_for_ides.md) | โ†‘ [User Guide](../user_guide.md) \ No newline at end of file diff --git a/doc/user_guide/reference/build_integration.md b/doc/user_guide/reference/build_integration.md new file mode 100644 index 000000000..c4b144440 --- /dev/null +++ b/doc/user_guide/reference/build_integration.md @@ -0,0 +1,10 @@ +### Build Integration + +To integrate requirement tracing with OFT into your CI build, we recommend using the OFT plugins for Maven and Gradle: + +* [openfasttrace-maven-plugin](https://github.com/itsallcode/openfasttrace-maven-plugin) +* [openfasttrace-gradle](https://github.com/itsallcode/openfasttrace-gradle) + +--- + +โ† [OFT Command Line](oft_command_line.md) | โ†‘ [Reference](reference.md) | [Input Format Support](input_format_support.md) โ†’ diff --git a/doc/user_guide/reference/console_tracing_report.md b/doc/user_guide/reference/console_tracing_report.md new file mode 100644 index 000000000..c268a2fd7 --- /dev/null +++ b/doc/user_guide/reference/console_tracing_report.md @@ -0,0 +1,80 @@ +### Console Tracing Report + +The Console Tracing Report is the standard report format of OFT. Its main purpose is to quickly debug broken tracing links. In this section you learn how to read this report. + +Below you see a typical example of a requirement from a design document. + + ok [ in: 2 / 2 โœ” | out: 1 / 1 โœ” ] dsn~cli.tracing.default-format~1 (impl, utest) + + The CLI uses plain text as requirement tracing report format if none is given as a parameter. + + [covered shallow ] โ† impl~cli.tracing.default-format-2215031703~0 + [covers ] โ†’ req~cli.tracing.default-output-format~1 + [covered shallow ] โ† utest~cli.tracing.default-format-3750270139~0 + +Let's go through its elements one by one. + +The first line is the summary. + +It starts with the status of the requirement — OK in this case. + +> **ok** [ in: 2 / 2 โœ” | out: 1 / 1 โœ” ] `dsn~cli.tracing.default-format~1` (impl, utest) + +Next we have a couple of numbers. + +The first pair shows how many of the incoming good links this requirement has (two), and how many in total (two). + +> ok [ **in: 2 / 2 โœ”** | out: 1 / 1 โœ” ] `dsn~cli.tracing.default-format~1` (impl, utest) + +Consequently, the next pair informs you how many (one) of the overall (one) outgoing links are good. + +Please note that OFT cannot predict the exact number of required incoming links, because often we are talking about one-to-many relations. So OFT does not try to. The checkmark and crossmark in the square brackets are only a quick indicator of if the existing links are okay. This goes so far that in case of zero links, no mark is displayed at all. + +> ok [ in: 2 / 2 โœ” | **out: 1 / 1 โœ”** ] `dsn~cli.tracing.default-format~1` (impl, utest) + +The [Specification Item ID](../../terminology.md#specification-item-id) in the middle is the unique technical ID of this requirement. + +> ok [ in: 2 / 2 โœ” | out: 1 / 1 โœ” ] **dsn****~****cli.tracing.default-format****~****1** (impl, utest) + +In the brackets you find which artifact types this item expects as coverage. If the type is covered correctly, you see just the name there. + +> ok [ in: 2 / 2 โœ” | out: 1 / 1 โœ” ] `dsn~cli.tracing.default-format~1` (**impl, utest**) + +If it is not covered, the name is lead in by a minus: + +> **not ok** … (**-impl**, utest) + +If an artifact type provides coverage that is not requested, you find this indicated with a plus in front. + +> **not ok** … (impl, **+itest**, utest) + + +If an item is covered correctly, but one of the items it covers has a defect itself, this is called a transitive defect. In this case, the item is marked as `not ok (transitive)`: + +> **not ok (transitive)** … (impl, utest) + +If there were any other specification objects defined with the same ID, you would see the following at the end of the summary line: + +> [has 3 duplicates] + +Everything after that line are details of the requirement. Indented text indicates this. The first part of the details is the description. + + The CLI uses plain text as requirement tracing report format if none is given as a parameter. + +The section with the arrows provides details about incoming and outgoing links. Arrows pointing to the left are incoming links, arrows pointing to the right are outgoing. You can easily remember this, since the arrows either point towards the ID of the connected specification item or away from it. + +The following line means that this design requirement is covered in the implementation. + +> [covered shallow ] โ† `impl~cli.tracing.default-format-2215031703~0` + +The ID of the implementation comes from the Tag Importer and is for its most part auto-generated. The artifact type `dsn` is simply replaced by `impl` here and a number is attached for disambiguation. + +> [covered shallow ] โ† **impl**~cli.tracing.default-format-**2215031703**~0 + +In the square brackets you find the status of the link. + +Just in case you are wondering about the extra spaces in some places of the report, those exist as padding to align multiple similar items in lists. + +--- + +โ† [Input Format Support](input_format_support.md) | โ†‘ [Reference](reference.md) | [Report Summary](report_summary.md) โ†’ diff --git a/doc/user_guide/reference/input_format_support.md b/doc/user_guide/reference/input_format_support.md new file mode 100644 index 000000000..f58c520f3 --- /dev/null +++ b/doc/user_guide/reference/input_format_support.md @@ -0,0 +1,166 @@ +### Input Format Support + +#### Tags in Programming Language or Markup Files + +The Tag Importer is the most basic importer OFT offers. While it supports a wide variety of source formats, it does not +really understand the surrounding format, but instead looks for certain patterns that define specification items. + +To avoid conflict with the formats actual contents, you embed these definitions in comments usually. + +Tags have the following format: + +``` +[ -> ] +``` + +Spaces above were only added for readability. They are optional. In fact usually people prefer a more compact form. +Here is an example of a tag embedded into a Java comment: + +```java +// [impl->dsn~validate-authentication-request~1] +private validate(final AuthenticationRequest request){ + // ... +} +``` + +##### Tags in Markdown and RST Documentation + +Markdown documentation files (`.md` and `.markdown`) and RST files (`.rst`) can cover specification items without being routed through the Tag Importer. Place a full tag in a standalone, single-line native comment: + +```markdown + +``` + +```rst +.. [doc->req~user-guide~1] +``` + +Only complete, standalone Markdown HTML comments and single-line RST comments are recognized. Inline or multi-line comments and RST directives do not import coverage tags. Text outside a native comment that merely resembles a tag is also ignored. + +##### Optional Elements + +Tags can optionally specify a revision number or name and revision number: + +``` +[ ~~ -> ] +[ ~ ~ -> ] +``` + +Examples: + +```java +// [impl~~2->dsn~validate-authentication-request~1] +// [impl~validate-password~2->dsn~validate-authentication-request~1] +``` + +##### Needed Coverage + +When using UML models as design document files like UML models it is useful to add needed coverage as well. To do this, you can use the following format: + +``` +[ -> >> ] +``` + +Example: + +``` +' [dsn->req~1password-login~1>>impl,test] +user -> system : login(token: OAuthToken) +``` + +##### Supported File Extensions + +The Tag Importer recognizes the supported format by the file extension. The following list shows the standard set of +recognized file types: + +**Programming languages** + +* Ada (`.ads`, `.adb`) +* C (`.c`, `.h`) +* C++ (`.C`, `.cpp`, `.c++`, `.cc`, `.H`, `.hpp`, `.h++`, `.hh`) +* C# (`.c#`, `cs`) +* Doxygen (`.dox`) +* Database related (`.sql`, `.pls`) +* Configuration files (`.cfg`, `.conf`, `.ini`) +* [Go](https://golang.org/) (`.go`) +* Groovy (`.groovy`) +* Java (`.java`, `.fxml`) +* JavaScript (`.js`, `.ejs`, `.cjs`, `.mjs`) +* Kotlin (`.kt`, `.kts`) +* Lua (`.lua`) +* Objective C (`.m`, `.mm`) +* Perl (`.pl`, `.pm`) +* PHP (`.php`) +* Protocol Buffers (`.proto`) +* Python (`.py`) +* R (`.r`) +* Rust (`.rs`) +* Shell programming (`.sh`, `.bash`, `.zsh`) +* Swift (`.swift`) +* Terraform (`.tf`, `.tfvars`) +* TypeScript (`.ts`) +* Windows batch files (`.bat`) + +**Configuration and Serialization Formats** + +* JSON (`.json`) +* Protobuf (`.proto`) +* TOML (`.toml`) + +**Markup languages** + +* HTML (`.html`, `.htm`, `.xhtml`) +* YAML (`.yaml`, `.yml`) +* XML (`xml`) + +**Modeling languages** + +* [PlantUML](https://plantuml.com) (`.pu`, `.puml`, `.plantuml`) + +Note that XML is at the moment not yet supported by the Tag Importer, because it would collide with the SpecObj Importer. Once import fallback is implemented, XML will be supported too. + +**Test Specification languages** + +* [Gherkin](https://cucumber.io/docs/gherkin/) (`.feature`) + +#### Gherkin + +OFT imports Gherkin `Scenario` and `Scenario Outline` blocks in `.feature` files when the immediately preceding tag region contains one OFT ID tag. Place optional `Covers` and `Needs` comments after the tags and before the scenario header: + +```gherkin +@smoke +@id:scn~user-can-log-in~1 +# Covers: req~authentication~1 +# Needs: dsn, itest +Scenario: A registered user logs in + Given a registered user + When they enter valid credentials + Then access is granted +``` + +The ID tag becomes the item location and the scenario header becomes its title; executable steps become the description. `Covers` and `Needs` are case-sensitive and optional. Multiple `Covers` comments accumulate coverage IDs, while `Needs` may appear once; all lists must be non-empty and comma-separated. Invalid IDs, types, or directives skip only the affected scenario and emit a warning. + +Existing full coverage tags remain supported in Gherkin comments, for example `# [impl~login~1 -> dsn~authentication~1]`. OFT deliberately ignores coverage-tag-shaped text in executable Gherkin lines. + +#### Markdown + +The main importer of OFT accepts Markdown files with the extensions `.md` and `.markdown`. + +#### SpecObject + +Elektrobit's SpecObject format is read from SpecObject files with the `.xml` extension. + +The SpecObject format is extended with support of namespaces to allow adding custom XML elements, e.g.: + +```xml + + + + + + +``` + +--- + +โ† [Build Integration](build_integration.md) | โ†‘ [Reference](reference.md) | [Console Tracing Report](console_tracing_report.md) โ†’ diff --git a/doc/user_guide/reference/oft_command_line.md b/doc/user_guide/reference/oft_command_line.md new file mode 100644 index 000000000..1c14e0394 --- /dev/null +++ b/doc/user_guide/reference/oft_command_line.md @@ -0,0 +1,131 @@ +### OFT Command Line + +The OFT command line looks like this: + + oft command [option ...] [ ...] + +or + + oft --help + +Where `command` is one of + +* `trace` - create a requirement trace document +* `convert` - convert to a different requirements format +* `help` - display a help message showing the command line usage and version of OFT + +and `option` is one or more of the options listed below. + +#### Display a Short Help Message + +The following commands are equivalent and all display the command line usage and the version of OFT. + + oft -h + oft --help + oft help + +#### Import options + + -a, --wanted-artifact-types [,...] + +Import only specification items where the artifact type matches one of the listed types. + + -w, --wanted-statuses [,...] + +Import only specification items that have a status contained in the comma-separated list of statuses. + + -t, --wanted-tags [_,][,...] + +Import only specification items that have at least one of the listed tags. If you add a single underscore "_" as the first entry in the list, specification items that have no tags at all are also imported. + +#### Tracing options + + -o, --output-format + +The format of the report. + +One of: +* `plain` +* `html` +* `aspec` + +Defaults to `plain`. + + --v, --report-verbosity + +The verbosity of the tracing report. + +* `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 +* `direct_failures` - list of specification items with non-transitive defects +* `failure_summaries` - list of summaries for defect specification items +* `direct_failure_summaries` - list of summaries for specification items with non-transitive defects +* `failure_details` - summaries and details for defect specification items +* `direct_failure_details` - summaries and details for specification items with non-transitive defects +* `overview` - summaries, link details and tags for all specification items, without the description +* `all` - summaries and details for all specification items + +Defaults to `failure_details`. + + --details-section-display + +Initial display status of the details section in the HTML report + +* `collapse` - hide details (default) +* `expand` - show details + +#### Converting Options + + -o, --output-format + +Format into which requirements are converted. + +One of +* `specobject` + +Defaults to `specobject`. + +#### Common Options + + -f, --output-file + +The output file or in case the output consists of more than one file, the output path. Defaults to STDOUT if not given. + + -i, --ignore-artifact-types ...] + +Choose one or more artifact types which are going to be ignored during import. Affects specification items of that type, needed coverage and links to specification items of that type. + + -n, --newline + +Newline format, one of +* `unix` +* `windows` +* `oldmac` + +Defaults to the platform standard if not given. + +You can change the output color scheme. + + -c, --color= + +The available color schemes are + +`black-and-white` +:: Plain black and white. On the console this also means no font styles used. + +`monochrome` +:: Black, white and shades of grey. Also enables font style on the console. + +`color` +:: Color output. Also enables font style on the console. + + + -l, --log-level + +Log level for console logging. One of `OFF`, `SEVERE`, `WARNING`, `INFO`, `CONFIG`, `FINE`, `FINER`, `FINEST`, `ALL`. Defaults to `WARNING`. + +--- + +โ† [Reference](reference.md) | โ†‘ [Reference](reference.md) | [Build Integration](build_integration.md) โ†’ diff --git a/doc/user_guide/reference/reference.md b/doc/user_guide/reference/reference.md new file mode 100644 index 000000000..d3cc8f8b4 --- /dev/null +++ b/doc/user_guide/reference/reference.md @@ -0,0 +1,21 @@ +--- +layout: default +title: Reference +parent: User Guide +has_children: true +--- + +## Reference + +The reference section provides detailed technical information about the OpenFastTrace command line interface, build system integration, supported formats, and report structures. + +* **[OFT Command Line](oft_command_line.md)**: Detailed syntax, commands, and options for running OFT from the console. +* **[Build Integration](build_integration.md)**: Instructions for integrating OFT into Maven and Gradle build pipelines. +* **[Input Format Support](input_format_support.md)**: Overview of supported programming languages and markup formats for requirement tags. +* **[Console Tracing Report](console_tracing_report.md)**: A guide to reading and interpreting the standard OFT console output for debugging. +* **[Report Summary](report_summary.md)**: Explanation of the summary statistics provided at the end of each trace. +* **[XML Tracing Report](xml_tracing_report.md)**: Documentation of the XML report format for machine-based processing and analysis. + +--- + +โ† [Understanding and Fixing Broken Requirement Branches](../use_cases/understanding_and_fixing_broken_requirement_branches.md) | โ†‘ [User Guide](../user_guide.md) | [OFT Command Line](oft_command_line.md) โ†’ diff --git a/doc/user_guide/reference/report_summary.md b/doc/user_guide/reference/report_summary.md new file mode 100644 index 000000000..7c8cae177 --- /dev/null +++ b/doc/user_guide/reference/report_summary.md @@ -0,0 +1,15 @@ +### Report Summary + +At the end of the report, a summary is displayed that informs you about the overall state of the trace. + +> **ok** - 123 total + +If there are defects, the summary provides more details: + +> **not ok** - 123 total, 5 direct, 2 transitive defects + +Here, "direct" means that the item itself has a coverage defect, and "transitive" means that the item is correctly covered, but one of the items it covers (or its descendants) has a defect. + +--- + +โ† [Console Tracing Report](console_tracing_report.md) | โ†‘ [Reference](reference.md) | [XML Tracing Report](xml_tracing_report.md) โ†’ diff --git a/doc/user_guide/reference/xml_tracing_report.md b/doc/user_guide/reference/xml_tracing_report.md new file mode 100644 index 000000000..7a15bd9f7 --- /dev/null +++ b/doc/user_guide/reference/xml_tracing_report.md @@ -0,0 +1,171 @@ +### XML Tracing Report + +Often users want to further process the results generated by OpenFastTrace to create statistics about requirements, +to add the results to a database or further analyze the results. OpenFastTrace therefore provides a reporter that +exports all relevant collected information into a single XML file that can further be processed by other tools. + +The XML exporter is called `aspec` reporter. `aspec` in this case means augmented specobject. An `aspec` report +can be generated by calling OpenFastTrace in the following way (replacing `` with the actual version): + +```sh +java -jar openfasttrace-.jar trace -o aspec -f requirements.xml requirements +``` + +OpenFastTrace needs to be executed with the command `trace` to activate the reporter. The `aspec` report is selected +with that parameter `-o aspec`. `-f` allows to provide the name of the output file into which the XML report is +generated. + +The `aspec` reporter generates an entry per processed requirement: + +* all relevant parameters of the requirement +* information if a requirement is successfully covered by other requirements +* information if all requirements covering a requirement are themselves successfully covered +* list of requirements covering a requirement +* list of requirements linked by a requirement + +The XML output roughly has the following structure + +```xml + + + + arch-my-architecture-requirement + ... + + ... + + ... + +``` + +`` is the toplevel XML element. Beneath the `` one `` entry can be found for +each requirement type found by OpenFastTrace. The element `` contains all requirements matching the type +named in ``. A `` XML tag wraps each requirement. + +A `` entry has the following form: + +```xml + + arch-my-architecture-requirement + 1 + The title + approved + architecture.md + 134 + Yet another architecture + + ... + + + ... + + + ... + + +``` + +`` and `` provide ID and version of the requirement. In OFT terminology the term revision is equal to + the version used in the aspec report. `` and `` provide title and description of the requirement. +`` and `` are the name and line number of the original file from which the requirement has been +imported. `` contains more information about the coverage of the requirement and lists other requirements +covering the requirement. + +`` contains requirements that have been marked as dependency. If parts of the information described above is +not available, the corresponding XML element is omitted in the generated report. + +The `` XML element has the following form: + +```xml + + + dsn + ... + + COVERED + UNCOVERED + + ... + + + dsn + + + impl + + +``` + +The `` elements provide the following sub elements: + +* ``: List of requirement types that are required to cover the requirement +* ``: `COVERED` if for all necessary requirement types, another valid requirement covers the requirement. + Valid in this case also means that the covering requirement has status `approved`. + `UNCOVERED` if not all required requirement types were covered successfully. +* ``: `COVERED` if all request requirement types are successfully covered by other requirements + that are themselves successfully covered transitively. `UNCOVERED` if the requirement is not successfully covered + transitively. +* ``: The `` element contains a sub element for each covering requirement. +* ``: List of requirement types that are shallowly covered. +* ``: List of requirement types that are not shallowly covered. + +The element `` describes all covering requirements: + +```xml + + + dsn-requirement + 1 + dsn + COVERED + COVERED + COVERING + + ... + +``` + +The element `` describes each requirement that provides a coverage to the enclosing requirement. Each covering requirement is described via the element ``. `` and `` provide the requirement ID and version of the requirement. `` provides the requirement type of the requirement. `` describes if the covering requirement is shallowly covered. A shallowly covered requirement is marked as `COVERED`. + +An uncovered requirement is reported as `UNCOVERED`. `` reports a transitive covered requirement with value `COVERED` and an uncovered requirement with value `UNCOVERED`. If the covering requirement itself transitively covers the enclosing requirement, `` reports the value `COVERING`. + +If the covering requirement does not cover the enclosing requirement `` reports `UNCOVERED`. If the covering requirement references the enclosing requirement with a wrong version `coveringStatus` reports `COVERING_WRONG_VERSION`. If the covering requirement is not expected to cover the enclosing requirement (e.g. it has an unexpected requirement type), the `` is reported as `UNEXPECTED`. + +A requirement described by the XML element `` lists all other requirements that it covers in the element ``: + +```xml + + + arch-requirement + 1 + arch + + ... + +``` + +For each covered requirement `` includes a `` element. A `` lists the referenced +requirement ID with the element ``, the requirement version with `` and the requirement type with the +element ``. + +If a requirement references other requirements without contributing to requirement coverage then all these references +are described by the element ``: + +```xml + + + arch-requirement + 1 + arch + + ... + +``` + +The `` element provides a `` element for each referenced requirement. The +`` element lists requirement ID with the element ``, the requirement version with `` +and the requirement type with the element ``. + +--- + +โ† [Report Summary](report_summary.md) | โ†‘ [Reference](reference.md) | [OFT API](../oft_api/oft_api.md) โ†’ diff --git a/doc/user_guide/tool_support/templates_for_ides.md b/doc/user_guide/tool_support/templates_for_ides.md new file mode 100644 index 000000000..766cb14f8 --- /dev/null +++ b/doc/user_guide/tool_support/templates_for_ides.md @@ -0,0 +1,7 @@ +### Templates for IDEs + +You can create OpenFastTrace artifacts faster with templates for your IDE. See [the list of available IDE Templates](https://github.com/itsallcode/openfasttrace-ide-templates). + +--- + +โ† [Tools for Authoring OFT Documents](tools_for_authoring_oft_documents.md) | โ†‘ [Tool Support](tool_support.md) | [Product Lifecycle](../product_lifecycle/product_lifecycle.md) โ†’ diff --git a/doc/user_guide/tool_support/tool_support.md b/doc/user_guide/tool_support/tool_support.md new file mode 100644 index 000000000..50a81534b --- /dev/null +++ b/doc/user_guide/tool_support/tool_support.md @@ -0,0 +1,12 @@ +--- +layout: default +title: Tool Support +parent: User Guide +has_children: true +--- + +## Tool Support + +--- + +โ† [Exit Codes](../oft_api/exit_codes.md) | โ†‘ [User Guide](../user_guide.md) | [Tools for Authoring OFT Documents](tools_for_authoring_oft_documents.md) โ†’ diff --git a/doc/user_guide/tool_support/tools_for_authoring_oft_documents.md b/doc/user_guide/tool_support/tools_for_authoring_oft_documents.md new file mode 100644 index 000000000..af85412a8 --- /dev/null +++ b/doc/user_guide/tool_support/tools_for_authoring_oft_documents.md @@ -0,0 +1,34 @@ +### Tools for Authoring OFT Documents + +The following editors and integrated development environments are well suited for authoring OFT documents. The list is not exhaustive, any editor with Markdown capabilities can be used. + +| Editor / IDE | Syntax
highlighting | Preview | Outline | HTML
export | OFT
Plugin | +|------------------------------------------------------|:-----------------------:|:-------:|:-------:|:---------------:|:--------------:| +| [CLion](https://www.jetbrains.com/clion/) | y | y | y | y | y | +| [Gedit](https://wiki.gnome.org/Apps/Gedit) | y | | | | | +| [Eclipse](https://eclipse.org) | y | y | y | y | y | +| [IntelliJ](https://www.jetbrains.com/idea/) | y | y | y | y | | +| [PyCharm](https://www.jetbrains.com/pycharm/) | y | | | | y | +| [Vim](https://www.vim.org/) | y | | | | | +| [Visual Studio Code](https://code.visualstudio.com/) | y | y | y | y | | + +Please note that some IDEs may require additional plugins to support Markdown features. + +#### IDE Plugins + +We offer plugins for the following popular IDEs. + +* [JetBrains IDEs (CLion, PyCharm, IntelliJ, etc.)](https://github.com/itsallcode/openfasttrace-intellij-plugin) + +Typical features include: + +* Syntax highlighting for OFT specification item IDs +* Symbol search for OFT specification items +* Navigation between OFT specification items +* Templates for OFT specification items +* Run configurations for OFT traces +* In-IDE trace report + +--- + +โ† [Tool Support](tool_support.md) | โ†‘ [Tool Support](tool_support.md) | [Templates for IDEs](templates_for_ides.md) โ†’ diff --git a/doc/user_guide/use_cases/delegating_requirement_coverage.md b/doc/user_guide/use_cases/delegating_requirement_coverage.md new file mode 100644 index 000000000..84130a48d --- /dev/null +++ b/doc/user_guide/use_cases/delegating_requirement_coverage.md @@ -0,0 +1,45 @@ +### Delegating Requirement Coverage + +Consider a situation where you are responsible for the high-level software architecture of your project. You define the component breakdown, the interfaces and the interworking of the components. You get your requirements from a system requirement specification, but it turns out many of those incoming requirements are at a detail level that does not require design decisions on inter-component-level but rather affects the internals of a single component. + +In those cases it would be a waste of time to repeat the original requirement in your architecture just to hand them down to the detailed design of a component. Instead, what you need is a fast way to express "yes, I read that requirement, and I am sure it does not need design decisions in the high-level architecture." + +To achieve this, OFT features a shorthand notation for delegating the job of covering a specification item to one or more different artifact types. + +In the following example, a requirement in the system requirement specification (artifact type `req`) stated that the web user interface of your product should use the corporate design. This clearly does not require an architectural decision (`arch`), so you forward it directly to the detailed design (`dsn`) level. + + arch --> dsn : req~web-ui-uses-corporate-design~1 + +Please note that the arrow is intentionally done with two dashes (`-->`) in order to reduce the chance for parsing collisions since the arrow with one dash often appears in documents. + +This notation can appear after: + +* A title +* "Needs" section +* "Depends" section +* "Covers" section +* "Tags" section + +If it appears in a multi-line text section of a requirement (description, comment or rationale) the forward is ignored. + +Note that a forward terminates the previous specification item, so the following notation does not work: + + `dsn~foo~1` + โ€ฆ + Covers: req~foo~1 + + dsn-->impl:req~bar~1 <-- this terminates the previous specification item + + Needs: impl,utest <-- this is now lost + +To avoid confusion, it is best to have all forwards in a separate section with their own title: + + # Forwarded Requirements + + * `dsn-->impl:req~bar~1` + * `dsn-->impl:req~zoo~2` + * `โ€ฆ` + +--- + +โ† [Excluding Parts of a Specification Document for OFT Parsing](excluding_parts_of_a_specification_document_for_oft_parsing.md) | โ†‘ [Use Cases](use_cases.md) | [Distributing the Detailing Work](distributing_the_detailing_work.md) โ†’ diff --git a/doc/user_guide/use_cases/distributing_the_detailing_work.md b/doc/user_guide/use_cases/distributing_the_detailing_work.md new file mode 100644 index 000000000..03c2727ae --- /dev/null +++ b/doc/user_guide/use_cases/distributing_the_detailing_work.md @@ -0,0 +1,35 @@ +### Distributing the Detailing Work + +In projects of a certain size you always reach the point where a single team is not enough to process the workload. As a consequence, the teams must find a way to distribute the work. A popular approach is splitting the architecture into components that are as independent as possible. Each team is then responsible for one or more distinct components. While the act of assigning the work should never be done inside the specification, at least the specification can prepare criteria on which to split the work. + +One proven way to do this is to use tags. The teams then decide for which specification items with which tags they are responsible. + +![Covering selected tags](../../images/uml/object/obj_multiple_detailed_designs.svg) + +In our example it is the job of Andrea the architect to create a system architecture for the system specification coming from Soeren. Andrea defines a set of components which communicate with each other through well-defined, minimal interfaces. Each component is designed so that it can be independently developed and tested. Only an integration test is later necessary to prove that the components work together as designed. You tag each architectural requirement with the names of the affected components. + +A typical requirement would then look like this (shortened to emphasize the "needs" and "tags" part): + + `arch~authentication-provider-requires-valid-client-certificate~1` + + The authentication provider accepts only connections from clients offering a client certificate ... + + Needs: dsn + + Tags: AuthenticationProvider + +The development teams distribute the components among themselves and use the tags to filter for only the [specification items](../../terminology.md#specification-item) they are responsible for. The teams then cover all of these in the detailed design and deliver everything to an integrator. The sum of all detailed designs must then cover the architectural design. + +Wan and Wu from the web service team in our example run an OFT convert job like this to pick the parts of the architecture they are affected by: + + oft convert -t AuthenticationProvider,ServiceDiscovery,MapProvider import/arch/ > arch_filtered_by_web_services.xml + +This tells OFT to read all known specification files from the directory "import/arch" and filter by a list of tags. The result is a list of requirements that match the tag filter. + +If you want to also import specification items that do not have any tags, add a single underscore "_" as the first entry in the comma-separated list of tags: + + oft convert -t _,AuthenticationProvider,ServiceDiscovery,MapProvider import/arch/ > arch_filtered_by_web_services.xml + +--- + +โ† [Delegating Requirement Coverage](delegating_requirement_coverage.md) | โ†‘ [Use Cases](use_cases.md) | [Filtering by Status](filtering_by_status.md) โ†’ diff --git a/doc/user_guide/use_cases/excluding_parts_of_a_specification_document_for_oft_parsing.md b/doc/user_guide/use_cases/excluding_parts_of_a_specification_document_for_oft_parsing.md new file mode 100644 index 000000000..a92e67466 --- /dev/null +++ b/doc/user_guide/use_cases/excluding_parts_of_a_specification_document_for_oft_parsing.md @@ -0,0 +1,23 @@ +### Excluding Parts of a Specification Document for OFT Parsing + +Sometimes you want specific sections or a whole document to be excluded from OFT parsing. One reason could be that it is a document that contains an OFT example, that should not contribute to the trace. Or, you could have data in a document and don't want to risk that something accidentally looks like an OFT artifact. + +To switch of scanning use the token `oft:on|off` in your document at the appropriate location. + +Markdown example: + + + This part is ignored by OFT. + + Here OFT scans again. + +ReStructured text example: + + .. oft:off + This part is ignored by OFT. + .. oft:on + Here OFT scans again. + +--- + +โ† [Writing a Specification](writing_a_specification.md) | โ†‘ [Use Cases](use_cases.md) | [Delegating Requirement Coverage](delegating_requirement_coverage.md) โ†’ diff --git a/doc/user_guide/use_cases/filtering_by_status.md b/doc/user_guide/use_cases/filtering_by_status.md new file mode 100644 index 000000000..14d370215 --- /dev/null +++ b/doc/user_guide/use_cases/filtering_by_status.md @@ -0,0 +1,15 @@ +### Filtering by Status + +Sometimes you only want to see specification items that have reached a certain maturity level. For example, you might want to create a report that only includes approved requirements. + +To achieve this, you can filter by status using the `-w` or `--wanted-statuses` option: + + oft trace -w approved doc/ + +This tells OFT to only import specification items that have the status `approved`. You can also provide a comma-separated list of statuses: + + oft trace -w approved,proposed doc/ + +--- + +โ† [Distributing the Detailing Work](distributing_the_detailing_work.md) | โ†‘ [Use Cases](use_cases.md) | [Tracing the Whole Chain](tracing_the_whole_chain.md) โ†’ diff --git a/doc/user_guide/use_cases/html_tracing_reports.md b/doc/user_guide/use_cases/html_tracing_reports.md new file mode 100644 index 000000000..b0b3177ad --- /dev/null +++ b/doc/user_guide/use_cases/html_tracing_reports.md @@ -0,0 +1,11 @@ +### HTML Tracing Reports + +While plain text reports are perfect for debugging your tracing chain, sometimes you need reports that are more optically appealing. This is usually true if you have to show reports to management or to quality assessors who usually focus on summaries and statistics rather than detail results. In this case you can tell OFT to create reports in HTML format by adding the `-o html` switch. + +```sh +oft trace -o html +``` + +--- + +โ† [Tracing the Whole Chain in the Same File System](tracing_the_whole_chain_in_the_same_file_system.md) | โ†‘ [Use Cases](use_cases.md) | [Understanding and Fixing Broken Requirement Branches](understanding_and_fixing_broken_requirement_branches.md) โ†’ diff --git a/doc/user_guide/use_cases/tracing_the_whole_chain.md b/doc/user_guide/use_cases/tracing_the_whole_chain.md new file mode 100644 index 000000000..5a42df730 --- /dev/null +++ b/doc/user_guide/use_cases/tracing_the_whole_chain.md @@ -0,0 +1,7 @@ +### Tracing the Whole Chain + +If you plan to assess the coverage state of your product as a whole, you need to trace the full chain including all artifacts. + +--- + +โ† [Filtering by Status](filtering_by_status.md) | โ†‘ [Use Cases](use_cases.md) | [Tracing the Whole Chain in the Same File System](tracing_the_whole_chain_in_the_same_file_system.md) โ†’ diff --git a/doc/user_guide/use_cases/tracing_the_whole_chain_in_the_same_file_system.md b/doc/user_guide/use_cases/tracing_the_whole_chain_in_the_same_file_system.md new file mode 100644 index 000000000..32b7c5248 --- /dev/null +++ b/doc/user_guide/use_cases/tracing_the_whole_chain_in_the_same_file_system.md @@ -0,0 +1,46 @@ +### Tracing the Whole Chain in the Same File System + +Preconditions: + +* All artifacts are readable for the user executing OFT + +Description: + +In a small project you probably have all artifacts in the same file system - most likely under a common root directory. +In this case the easiest way to get a full trace is to list all the directories that OFT should search for artifacts to import. + +Let's assume a typical Java project with the following directory layout: + + /home/git/my-project + |-- doc manuals, requirement specification and design + |-- src + | |-- main + | | '-- java implementation + | '-- test + ... '-- java unit and integration tests + + +In this case the minimal OFT command line looks like this: + +```sh +PROJECT_ROOT='/home/git/my-project/' +oft trace "$PROJECT_ROOT"/doc "$PROJECT_ROOT"/src/main/java "$PROJECT_ROOT"/src/test/java +``` + +Or if you prefer it shorter: + +```sh +cd /home/git/my-project/ +oft trace doc src/main/java src/test/java +``` + +The first variant is better suited for integration into scripts where you usually want to avoid changing the directory. + +By default, this will produce a plain text trace that displays details of all defect specification items and a summary. + +See also: +* [Tracing Options](../reference/oft_command_line.md#tracing-options) for controlling the tracing output + +--- + +โ† [Tracing the Whole Chain](tracing_the_whole_chain.md) | โ†‘ [Use Cases](use_cases.md) | [HTML Tracing Reports](html_tracing_reports.md) โ†’ diff --git a/doc/user_guide/use_cases/understanding_and_fixing_broken_requirement_branches.md b/doc/user_guide/use_cases/understanding_and_fixing_broken_requirement_branches.md new file mode 100644 index 000000000..e308c1385 --- /dev/null +++ b/doc/user_guide/use_cases/understanding_and_fixing_broken_requirement_branches.md @@ -0,0 +1,73 @@ +### Understanding and Fixing Broken Requirement Branches + +Requirements โ€” or specification items as we call them more broadly โ€” in OFT are internally organized in a graph. If you haven't heard of that term, don't worry. In most cases it is close enough to think of the relationships between the specification items like a forest where the highest level of the specification are tree trunks from which details branch out into big branches, twigs and eventually leaves. + +Requirement engineering calls this the "traceability matrix". That term is a bit clunky, but we thought, you should have heard of it at least once. + +#### Everything That can go Wrongโ€ฆ + +What we want to achieve in any role that has to do with requirement engineering is healthy trees with their leaves attached all the way to the trunks. We don't want twigs without leaves, and we definitely don't want leaves lying on the ground. + +Unfortunately, we are only human, and humans make mistakes. Here is a non-exhaustive list of typical mistakes that happen when maintaining a traceability matrix: + +| Mistake | How it manifests in OFT | +|---------------------------------|----------------------------------------------------| +| Unimplemented feature | missing leaves in the implementation | +| Missing tests | missing leaves in the test | +| Typos in requirement IDs | causing branches to be cut somewhere in the middle | +| Wrong artifact type in coverage | both missing and unexpected coverage | + +#### Reading and Understanding the Link Error Types + +Depending, from where you look at a specification item, it can have links that point towards it (incoming) or away from it (outgoing). And those links can be broken. This is a typical sign that the requirement matrix contains wrong coverage, is incomplete or has excess parts. + +#### Outgoing Link Statuses + +| Status | Explanation | Ok | +|------------------|------------------------------------------------------------------------|----| +| Covers | This item covers another item | โœ”๏ธ | +| Predated | This item covers a newer revision of another item | โŒ | +| Outdated | This item covers an older revision of another item | โŒ | +| Ambiguous | Two items with the same id are covered by another item | โŒ | +| Unwanted | This item covers another item that does not require this coverage | โŒ | +| Orphaned | This item covers a non-existing item | โŒ | + +"Covers" means everything is fine. + +When the outgoing link from this item is "predated", that means it points to a newer version of the covered item than it should. This is usually a typo that you need to simply fix. On rarer occasion it can hint at a merge error or a problem when multiple teams contribute to the same specification. Check the document history if unsure. + +"Outdated" coverage typically happens when an existing specification item was updated, but the coverage wasn't. This is one of the most useful safeguards in OFT. + +Copy & paste often leads to "ambiguous" coverage, where two items are defined with the same ID. Treat this like you would fix a typo, but be careful, if the ID wasn't updated, then there are likely other copy & paste errors hiding in the vicinity. + +Coverage is "unwanted" when the specification item that it points to didn't ask for it. Check for typos in both IDs. The most common mistake here is that either the required artifact types or the coveraging artifact types are wrong. + +"Orphaned" finally means that this item claims to cover a requirement that does not exist. Or ceased to exist. In this case first check for typos, and if it is not a typo, check the history of the documents to see if there is maybe coverage left for something that has been obsoleted higher up in a specification. + + +#### Incoming Link Statuses + +| Status | Explanation | Ok | +|------------------|--------------------------------------------------------------------------|----| +| Covered Shallow | This item is directly covered by another item | โœ”๏ธ | +| Covered Unwanted | This item is covered by another item though it does not require coverage | โŒ | +| Covered Predated | This item is covered by another item that specifies a newer revision | โŒ | +| Covered Outdated | This item is covered by another item that specifies an older revision | โŒ | + +If you see "covered shallow" on an incoming link, this means that there is at least one specification item providing the required coverage. + +"Covered unwanted" means that another item covers the one you are looking at, but it shouldn't, because that coverage was not required. In most cases you are looking at a copy & paste error. Sometimes it is simply a typo in the artifact types. In rarer circumstances this happens the person who wrote the higher level item disagreed with the one who did the coverage. The last variant can be solved by talking to each other. + +"Covered predated" means some other specification item claims to cover a newer version of this item than is currently present in the spec. "Covered outdated" is the opposite situation. The problem resolution is the same as in the [section above](#outgoing-link-statuses) where the predated and outdated incoming links were discussed. + +#### Bidirectional Link Statuses + +| Status | Explanation | Ok | +|------------------|--------------------------------------------------------------------------|----| +| Duplicate | Two items have the same ID | โŒ | + +Duplicate links are special. They don't have a clear direction, since OFT cannot tell which specification item is the original and which one is the duplicate. In either case, you are most likely looking at a copy & past error again. Handle this with care and check if you maybe forgot to adapt other aspects of the copy too, not only the ID. + +--- + +โ† [HTML Tracing Reports](html_tracing_reports.md) | โ†‘ [Use Cases](use_cases.md) | [Reference](../reference/reference.md) โ†’ diff --git a/doc/user_guide/use_cases/use_cases.md b/doc/user_guide/use_cases/use_cases.md new file mode 100644 index 000000000..17993bb7a --- /dev/null +++ b/doc/user_guide/use_cases/use_cases.md @@ -0,0 +1,24 @@ +--- +layout: default +title: Use Cases +parent: User Guide +has_children: true +--- + +## Use Cases + +The following use cases describe common tasks and workflows when using OpenFastTrace. + +* **[Writing a Specification](writing_a_specification.md)**: Learn how to author requirement specifications using Markdown and OFT-readable specification items. +* **[Excluding Parts of a Specification Document for OFT Parsing](excluding_parts_of_a_specification_document_for_oft_parsing.md)**: Use `oft:on|off` tokens to exclude specific sections or whole documents from being scanned by OFT. +* **[Delegating Requirement Coverage](delegating_requirement_coverage.md)**: Use shorthand notation to forward the responsibility of covering a specification item to different artifact types. +* **[Distributing the Detailing Work](distributing_the_detailing_work.md)**: Use tags to split the architecture and distribute work across different teams. +* **[Filtering by Status](filtering_by_status.md)**: Create reports that only include specification items matching specific maturity levels (e.g., approved). +* **[Tracing the Whole Chain](tracing_the_whole_chain.md)**: Assess the coverage state of your entire product by tracing the full chain of artifacts. +* **[Tracing the Whole Chain in the Same File System](tracing_the_whole_chain_in_the_same_file_system.md)**: Perform a full trace in small projects where all artifacts are located under a common root directory. +* **[HTML Tracing Reports](html_tracing_reports.md)**: Generate visually appealing HTML reports for management or quality assessments. +* **[Understanding and Fixing Broken Requirement Branches](understanding_and_fixing_broken_requirement_branches.md)**: Identify and resolve issues in the traceability graph to ensure all requirements are properly linked. + +--- + +โ† [Windows Installation](../installation/windows.md) | โ†‘ [User Guide](../user_guide.md) | [Writing a Specification](writing_a_specification.md) โ†’ diff --git a/doc/user_guide/use_cases/writing_a_specification.md b/doc/user_guide/use_cases/writing_a_specification.md new file mode 100644 index 000000000..d23711a51 --- /dev/null +++ b/doc/user_guide/use_cases/writing_a_specification.md @@ -0,0 +1,178 @@ +### Writing a Specification + +Preconditions: +* Text editor (preferably with syntax highlighting for [Markdown](https://daringfireball.net/projects/markdown/)) + +OFT's native format for writing specifications is [Markdown](https://daringfireball.net/projects/markdown/). Markdown is an easy to learn, easy to read markup format that can be written with any text editor and is typically rendered to HTML. For your convenience we recommend using an editor that provides at least syntax highlighting. A preview function is also helpful. In the best case it features an outline view too. Check ["Tools for Authoring OFT Documents"](../tool_support/tools_for_authoring_oft_documents.md#tools-for-authoring-oft-documents) for some suggestions. + +While OFT introduces additional syntax rules so that it can distinguish between [informative](../../terminology.md#informative-passage) and [normative passages](../../terminology.md#normative-passage), all elements are valid Markdown. + +Let's start with a minimal requirement: + + `req~this-is-the-id~1` + + This is the description of the requirement. + +Simple as this. This is already a valid and complete OFT requirement. Of course, you can enrich the requirement with other information, but at the heart of it every requirement is an ID and a description. + +It is mostly a matter of taste whether you prefer your specification items to have a title or not. The same requirement above with a title looks like this: + + ### The Requirement Title + `req~this-is-the-id~1` + + This is the description of the requirement. + +Since version 3.8.0 OFT also supports titles with underlines. Since Markdown only allows first level (H1) and second level (H2) titles to be underlined with '=' and '-' respectively and requirements are usually nested deeper into a document, we recommend sticking to the hash mark style of titles though. Underlined titles are mainly supported for compatibility with ReStructured Text (RST). + + A Requirement Title With an Underline + ------------------------------------- + `req~this-is-the-id~1` + + This is the description of the requirement. + +The upside of giving requirements a title is that they appear in Markdown outline views. The downside is that they introduce redundancy in your specification and therefore have the tendency to become inconsistent with the content of the specification item. If you think in software design terms, the titles violate the ["Don't Repeat Yourself" principle (DRY)](https://en.wikipedia.org/wiki/Don't_repeat_yourself). + +The number of hash marks in front of the title must adhere to the rules of Markdown, meaning that if you want to put a [specification item](../../terminology.md#specification-item) inside a section with a level two header, the item title must start with three hash marks. + +At the moment the specification item above is a [terminating item](../../terminology.md#terminating-specification-item) because it does not require coverage by any [artifact type](../../terminology.md#artifact-type). Since a user level requirement always needs coverage in other artifact types, we are going to add this next. + + ### The Requirement Title + `req~this-is-the-id~1` + + This is the description of the requirement. + + Needs: dsn, uman + +Now the item must be covered in the design ("dsn") and user manual ("uman"). Remember you can introduce your own artifact types depending on the needs of your project. + +Of course, you can embed specification items into normal Markdown text. This adds the necessary [informative](../../terminology.md#informative-passage) context that is required to understand the [normative passages](../../terminology.md#normative-passage). + + # ACME portable hole + + ## Introduction + + This document describes the user requirements for the ACME portable hole + ... + + ## Functional Requirements + + This section lists the functional requirements of the ACME portable hole. + Non-functional requirements are described in the section + [quality scenarios](#quality-scenarios). + + ### The Requirement Title + `req~this-is-the-id~1` + + This is the description of the requirement. + + Needs: dsn, uman + +Requirements should be accompanied by a rationale in all cases where the reason for the requirement is not immediately obvious. A comment can be used for explanatory parts, warnings or other information that is neither normative nor fits into the rationale. + + `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 + +`Needs`, `Rationale` and `Comment` are OpenFastTrace keywords that tell OpenFastTrace how to process the following content. There are other keywords in the context of specification items written in Markdown described in the following sections. + +#### Keywords + +Keywords are followed by a colon that separates the keyword from the content. Depending on the keyword, the content may start on the next line. + +##### `Status` + +The `Status` keyword takes a single value from `draft`, `proposed`, `approved`, `rejected` to set the status of the item. The status can be used to filter specification items during import (see [Import options](../reference/oft_command_line.md#import-options)). Has to occur before the `Description`, `Rationale` or `Comment`. + + ### A draft spec items + `req~draft-item~1` + Status: draft + + This spec item is in the draft state and thus not considered final. + + +##### `Covers` + +The `Covers` keyword states which items are covered by the current specification item. It is followed by a list of items that are covered, each one written on a new line starting with a bullet character (`+`, `*`, or `-`) followed by the referenced specification item id. + +Given the Feature `feat~rubber-ducky~1` exists and needs a `req`. A requirement that covers that feature could be written as + + ### Rubber ducky is made from latex + `req~rubber-ducky-made-from-latex~1` + + The rubber ducky should be made from latex. + + Rationale: + We'd like to avoid using materials made from crude oil and therefor use latex instead, because it is made from sustainable, regrowable resources. + + Covers: + - feat~rubber-ducky~1 + +##### `Needs` + +The `Needs` keyword states which artifact types are needed to cover the current specification item. It is followed by a list of artifact types that are needed, each one written on a new line starting with a bullet character (`+`, `*`, or `-`) followed by the artifact type abbreviation. `Needs` comes in two flavors: as one-liner or as list. + +**Variant a) one-line `needs`** + + Needs: impl, utest, itest + +**Variant b) as List** + + Needs: + - dsn + - uman + +Please note that you cannot mix the two styles in one specification item. + +##### `Depends` + +The `Depends` keyword defines dependencies between specification items. It is followed by a list of items the current specification item depends on, each one written on a new line starting with a bullet character (`+`, `*`, or `-`) followed by the referenced specification item id. At the moment this has no effect on the HTML or plaintext output, but only if the `-o aspec` option is used. This has no effect on the coverage of specification items. + + ### Depending specification item + `req~depending-item~1` + + This item depends on two others. + + Depends: + - req~dependency-1~1 + - req~dependency-2~1 + +##### `Description` + +This keyword is *optional*. Starts the text passage that describes a specification item. The description is automatically started with any non-empty text that does not start with another keyword. Has to occur before `Comment` or `Rationale`. The specification item + + ### Specification item + `feat~specification-item~1` + + Description: + This is the description. + +is functionally equivalent to + + ### Specification item + `feat~specification-item~1` + + This is the description. + +##### `Tags` + +Tags are described in detail later in this document, see section [Distributing the Detailing Work](distributing_the_detailing_work.md#distributing-the-detailing-work). + +--- + +โ† [Use Cases](use_cases.md) | โ†‘ [Use Cases](use_cases.md) | [Excluding Parts of a Specification Document for OFT Parsing](excluding_parts_of_a_specification_document_for_oft_parsing.md) โ†’ + +### Quality Scenarios + +*Note: This section is a placeholder referenced in the example above.* diff --git a/doc/user_guide/user_guide.md b/doc/user_guide/user_guide.md index 837864b39..05d916aa3 100644 --- a/doc/user_guide/user_guide.md +++ b/doc/user_guide/user_guide.md @@ -1,1315 +1,58 @@ -![oft-logo](../../core/src/main/resources/openfasttrace_logo.svg) +--- +layout: default +title: User Guide +nav_order: 2 +has_children: true +--- + +![oft-logo](../images/openfasttrace_logo.svg) # OpenFastTrace (OFT) User Guide ## In a Nutshell -OFT is a requirement tracing tool. It helps you make sure that all defined requirements are covered in your code. It -also helps you find outdated code passages. +OFT is a requirement tracing tool. It helps you make sure that all defined requirements are covered in your code. It also helps you find outdated code passages. 1. Create requirement and specification documents in Markdown, including OFT-readable specification items 2. Put tags into your source code that mark the coverage of items from the specification 3. Use OFT to trace the requirements from the source to the final implementation -## Introduction - -### Who Should Read This Document? - -This document is mainly targeted at users wanting to learn how to use OFT for authoring requirement specifications, tracing requirement coverage and converting between requirement formats. - -In software projects those users are typically: - -* Technical writers -* Requirement engineers -* Software developers -* Quality engineers - -For this class of users all sections are of interest. - -The document is also helpful for people who just want to get an insight on what OFT is good for and the ideas behind it like: - -* Project managers -* IT Support personnel -* People responsible for picking tools (who we recommend should be users too) - -Of course, requirement engineering and tracing are useful outside the software domains too. - -### What is Requirement Tracing? - -OpenFastTrace is a requirement tracing suite. Requirement tracing helps you to keep track of whether you actually implemented everything you planned to in your specifications. It also identifies obsolete parts of your product and helps you to get rid of them. - -The foundation of all requirement tracing is links between documents, implementation, test, reports and whatever other artifacts your product consists of. - -Let's assume you compiled a list of five main features your users asked for. They are very coarse but provide a nice overview of what your project is expected to achieve. Next you decide to write a few dozen user stories to flesh out the details of what your users want. - -In order not to forget anything important, you create a link from each user story to the corresponding feature. - -After you are done you want to make sure everything is in order. Instead of checking all the links by hand, you let OFT check if every feature is covered in at least one user story. - -OFT comes back with a result that one of your features is not covered. You realize that you indeed forgot that one, write two new user stories and link them to the so far uncovered feature. This time OFT comes back with an assuring "OK". - -Step-by-step you repeat this pattern for your design document and all resulting artifacts. - -### Why do I Need Requirement Tracing? - -Requirement tracing is a safety net for non-trivial software projects: - -* protects you from forgetting planned parts of your product -* finds orphaned code, documents and resources -* helps you track progress towards milestones -* allows you to prove due diligence during quality audits and customer reviews - -### Concepts and Terms - -There are some often used terms in the OFT documentation that stand for concepts you should be familiar with when using OFT. - -#### Specification Item - -"Specification Item" is the general term we use to denominate all normative pieces of specifications and markers to their coverage in the implementation. - -Examples: -* Feature definitions -* Requirements in a system requirement specification -* Markers in implementation and tests that signal [coverage](#coverage) - -We use this term to better distinguish between the accepted use of the word "requirement" which most people only use for specification items found in requirement documents and the broader use that includes coverage markers. - -#### Specification Item ID - -The identifier (ID) of a [specification item](#specification-item) is a project-globally unique key which is used to refer to a specification item. - -The specification item ID consists of the following parts: -* [Artifact type](#specification-item-artifact-type) -* [Name](#specification-item-name) -* [Revision](#specification-item-revision) - -All parts are integral to the ID. The name alone is neither unique nor complete. In OFT's native document formats the ID is represented as a character string where the three parts are separated by the tilde (`~`) symbol. - -Examples: - - feat~html-export~1 - req~html5-exporter~1 - dsn~html5-exporter~1 - utest~html5-exporter~4 - -The following sections explain the each of the three parts in detail. - -##### Specification Item Artifact Type - -The artifact type serves two purposes: - -1. identifying the source document type -2. identifying the position in the tracing hierarchy - -Artifact types are represented by character strings consisting out of ASCII letters. No other characters are allowed. - -While not enforced by OFT the following strings are well established: - -* `feat` - high-level feature -* `req` - user requirement -* `arch` - architectural requirement -* `dsn` - design requirement -* `impl` - implementation -* `utest` - unit test -* `itest` - integration test -* `stest` - system test -* `uman` - user manual -* `oman` - operation manual - -If you don't distinguish between architectural and detailed design we recommend using `dsn` for both. The OFT specification for example does it that way. - -How many types you introduce, how you name and stack them is up to you. When we designed OFT, we were clear about the fact that we would not be able to cover all possible artifact types one could imagine, so we did not hardcode them into OFT. - -##### Specification Item Name - -The name part of the ID must be a character string consisting of Unicode letters and/or numbers separated by underscore (`_`), hyphen (`-`) or dot (`.`). Whitespaces are not allowed. - -* Names must start with a unicode letter -* Consecutive dots `.` are not allowed - -We recommend using a dot `.` to create a hierarchy of items: - - exporter.html5.folding - exporter.html5.colors - exporter.csv.column_names - -##### Specification Item Revision - -The revision number of a specification item is a positive integer number that can be started at zero but by convention usually is started at one. - -The revision is intended to obsolete existing coverage links in case the content of a specification item semantically changed. Incrementing the revision voids all existing links to this item so that authors linking to the item know they have to check for changes and adapt the covering items. - -Examples: - -If you change a requirement that lists all browsers that an HTML export needs to be compatible with, you made a semantic change and should raise the revision number. - -If on the other hand you only added a missing period at the end of a sentence, the requirement content did not really change and there is no need to invalidate existing coverage. - -#### Informative Passages - -Informative passages of a specification provide explanations and context that is necessary for understanding the subject. They do not require coverage though. - -#### Normative Passages - -Normative passages contain requirements (or in OFT terms ["specification items"](#specification-item)). Unlike [informative passages](#informative-passages) they require that someone details, implements or verifies the contained specification items. - -#### Coverage - -The term "coverage" describes the relation between [specification items](#specification-item) that require detailing, implementation or verification and the items providing just that. This is done by listing all [artifact types](#specification-item-artifact-type) where the author of a specification item expects to see coverage for that item. - -A specification item is covered when for each of the required artifact types at least one item exists that covers the original item. - -#### Deep Coverage - -Deep coverage is a special form of coverage. Achieving deep coverage means that not only is a [specification item](#specification-item) covered by all required [artifact types](#specification-item-artifact-type), but also the covering items are all covered. - -If an item has shallow coverage but its covering items are not fully covered themselves, it has a [transitive defect](#transitive-defects). - -#### Terminating Specification Item - -A [specification item](#specification-item) terminates a chain of items if it does not require coverage in any [artifact type](#specification-item-artifact-type). - -Example: - - "feat" --needs--> "req" --needs--> "dsn" --needs--> "impl" (terminates chain) - |----> "utest" (terminates chain) - '----> "itest" (terminates chain) - -## Use Cases - -### Writing a Specification - -Preconditions: -* Text editor (preferably with syntax highlighting for [Markdown](https://daringfireball.net/projects/markdown/)) - -OFT's native format for writing specifications is [Markdown](https://daringfireball.net/projects/markdown/). Markdown is an easy to learn, easy to read markup format that can be written with any text editor and is typically rendered to HTML. For your convenience we recommend using an editor that provides at least syntax highlighting. A preview function is also helpful. In the best case it features an outline view too. Check ["Tools for Authoring OFT Documents"](#tools-for-authoring-oft-documents) for some suggestions. - -While OFT introduces additional syntax rules so that it can distinguish between [informative](#informative-passages) and [normative passages](#normative-passages), all elements are valid Markdown. - -Let's start with a minimal requirement: - - `req~this-is-the-id~1` - - This is the description of the requirement. - -Simple as this. This is already a valid and complete OFT requirement. Of course, you can enrich the requirement with other information but at the heart of it every requirement is an ID and a description. - -It is mostly a matter of taste whether you prefer your specification items to have a title or not. The same requirement above with a title looks like this: - - ### The Requirement Title - `req~this-is-the-id~1` - - This is the description of the requirement. - -Since version 3.8.0 OFT also supports titles with underlines. Since Markdown only allows first level (H1) and second level (H2) titles to be underlined with '=' and '-' respectively and requirements are usually nested deeper into a document, we recommend sticking to the hash mark style of titles though. Underlined titles are mainly supported for compatibility with ReStructured Text (RST). - - A Requirement Title With an Underline - ------------------------------------- - `req~this-is-the-id~1` - - This is the description of the requirement. - -The upside of giving requirements a title is that they appear in Markdown outline views. The downside is that they introduce redundancy in your specification and therefore have the tendency to become inconsistent with the content of the specification item. If you think in software design terms, the titles violate the ["Don't Repeat Yourself" principle (DRY)](https://en.wikipedia.org/wiki/Don't_repeat_yourself). - -The number of hash marks in front of the title must adhere to the rules of Markdown, meaning that if you want to put a [specification item](#specification-item) inside a section with a level two header, the item title must start with three hash marks. - -At the moment the specification item above is a [terminating item](#terminating-specification-item) because it does not require coverage by any [artifact type](#specification-item-artifact-type). Since a user level requirement always needs coverage in other artifact types, we are going to add this next. - - ### The Requirement Title - `req~this-is-the-id~1` - - This is the description of the requirement. - - Needs: dsn, uman - -Now the item must be covered in the design ("dsn") and user manual ("uman"). Remember you can introduce your own artifact types depending on the needs of your project. - -Of course, you can embed specification items into normal Markdown text. This adds the necessary [informative](#informative-passages) context that is required to understand the [normative passages](#normative-passages). - - # ACME portable hole - - ## Introduction - - This document describes the user requirements for the ACME portable hole - ... - - ## Functional Requirements - - This section lists the functional requirements of the ACME portable hole. - Non-functional requirements are described in the section - [quality scenarios](#quality-scenarios). - - ### The Requirement Title - `req~this-is-the-id~1` - - This is the description of the requirement. - - Needs: dsn, uman - -Requirements should be accompanied by a rationale in all cases where the reason for the requirement is not immediately obvious. A comment can be used for explanatory parts, warnings or other information that is neither normative nor fits into the rationale. - - `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 - -`Needs`, `Rationale` and `Comment` are OpenFastTrace keywords that tell OpenFastTrace how to process the following content. There are other keywords in the context of specification items written in Markdown described in the following sections. - -#### Keywords - -Keywords are followed by a colon that separates the keyword from the content. Depending on the keyword, the content may start on the next line. - -##### `Status` - -The `Status` keyword takes a single value from `draft`, `proposed`, `approved`, `rejected` to set the status of the item. The status can be used to filter specification items during import (see [Import options](#import-options)). Has to occur before the `Description`, `Rationale` or `Comment`. - - ### A draft spec items - `req~draft-item~1` - Status: draft - - This spec item is in the draft state and thus not considered final. - - -##### `Covers` - -The `Covers` keyword states which items are covered by the current specification item. It is followed by a list of items that are covered, each one written on a new line starting with a bullet character (`+`, `*`, or `-`) followed by the referenced specification item id. - -Given the Feature `feat~rubber-ducky~1` exists and needs a `req`. A requirement that covers that feature, could be written as - - ### Rubber ducky is made from latex - `req~rubber-ducky-made-from-latex~1` - - The rubber ducky should be made from latex. - - Rationale: - We'd like to avoid using materials made from crude oil and therefor use latex instead, because it is made from sustainable, regrowable resources. - - Covers: - - feat~rubber-ducky~1 - -##### `Needs` - -The `Needs` keyword states which artifact types are needed to cover the current specification item. It is followed by a list of artifact types that are needed, each one written on a new line starting with a bullet character (`+`, `*`, or `-`) followed by the artifact type abbreviation. `Needs` comes in two flavors: as one-liner or as list. - -**Variant a) one-line `needs`** - - Needs: impl, utest, itest - -**Variant b) as List** - - Needs: - - dsn - - uman - -Please note that you cannot mix the two styles in one specification item. - -##### `Depends` - -The `Depends` keyword defines dependencies between specification items. It is followed by a list of items the current specification item depends on, each one written on a new line starting witch a bullet character (`+`, `*`, or `-`) followed by the referenced specification item id. At the moment this has no effect on the HTML or plaintext output, but only if the `-o aspec` option is used. This has no effect on the coverage of specification items. - - ### Depending specification item - `req~depending-item~1` - - This item depends on two others. - - Depends: - - req~dependency-1~1 - - req~dependency-2~1 - -##### `Description` - -This keyword is *optional*. Starts the text passage that describes a specification item. The description is automatically started with any non-empty text that does not start with another keyword. Has to occur before `Comment` or `Rationale`. The specification item - - ### Specification item - `feat~specification-item~1` - - Description: - This is the description. - -is functionally equivalent to - - ### Specification item - `feat~specification-item~1` - - This is the description. - -##### `Tags` - -Tags are described in detail later in this document, see section [Distributing the Detailing Work](#distributing-the-detailing-work). - -### Excluding Parts of a Specification Document for OFT Parsing - -Sometimes you want specific sections or a whole document to be excluded from OFT parsing. One reason could be that it is a document that contains an OFT example, that should not contribute to the trace. Or, you could have data in a document and don't want to risk that something accidentally looks like an OFT artifact. - -To switch of scanning use the token `oft:on|off` in your document at the appropriate location. - -Markdown example: - - - This part is ignored by OFT. - - Here OFT scans again. - -ReStructured text example: - - .. oft:off - This part is ignored by OFT. - .. oft:on - Here OFT scans again. - -### Delegating Requirement Coverage - -Consider a situation where you are responsible for the high-level software architecture of your project. You define the component breakdown, the interfaces and the interworking of the components. You get your requirements from a system requirement specification, but it turns out many of those incoming requirements are at a detail level that does not require design decisions on inter-component-level but rather affects the internals of a single component. - -In those cases it would be a waste of time to repeat the original requirement in your architecture just to hand them down to the detailed design of a component. Instead, what you need is a fast way to express "yes, I read that requirement, and I am sure it does not need design decisions in the high-level architecture." - -To achieve this OFT features a shorthand notation for delegating the job of covering a specification item to one or more different artifact types. - -In the following example a requirement in the system requirement specification (artifact type `req`) stated that the web user interface of your product should use the corporate design. This clearly does not require an architectural decision (`arch`), so you forward it directly to the detailed design (`dsn`) level. - - arch --> dsn : req~web-ui-uses-corporate-design~1 - -Please note that the arrow is intentionally done with two dashes (`-->`) in order to reduce the chance for parsing collisions since the arrow with one dash often appears in documents. - -This notation can appear after: - -* A title -* "Needs" section -* "Depends" section -* "Covers" section -* "Tags" section - -If it appears in a multi-line text section of a requirement (description, comment or rationale) the forward is ignored. - -Note that a forward terminates the previous specification item, so the following notation does not work: - - `dsn~foo~1` - โ€ฆ - Covers: req~foo~1 - - dsn-->impl:req~bar~1 <-- this terminates the previous specification item - - Needs: impl,utest <-- this is now lost - -To avoid confusion, it is best to have all forwards in a separate section with their own title: - - # Forwarded Requirements - - * `dsn-->impl:req~bar~1` - * `dsn-->impl:req~zoo~2` - * `โ€ฆ` - -### Distributing the Detailing Work - -In projects of a certain size you always reach the point where a single team is not enough to process the workload. As a consequence the teams must find a way to distribute the work. A popular approach is splitting the architecture into components that are as independent as possible. Each team is then responsible for one or more distinct components. While the act of assigning the work should never be done inside the specification, at least the specification can prepare criteria on which to split the work. - -One proven way to do this is to use tags. The teams then decide for which specification items with which tags they are responsible. - -![Covering selected tags](../images/uml/object/obj_multiple_detailed_designs.svg) - -In our example it is the job of Andrea the architect to create a system architecture for the system specification coming from Soeren. Andrea defines a set of components which communicate with each other through well-defined, minimal interfaces. Each component is designed so that it can be independently developed and tested. Only an integration test is later necessary to prove that the components work together as designed. You tag each architectural requirement with the names of the affected components. - -A typical requirement would then look like this (shortened to emphasize the "needs" and "tags" part): - - `arch~authentication-provider-requires-valid-client-certificate~1` - - The authentication provider accepts only connections from clients offering a client certificate ... - - Needs: dsn - - Tags: AuthenticationProvider - -The development teams distribute the components among themselves and use the tags to filter for only the [specification items](#specification-item) they are responsible for. The teams then cover all of these in the detailed design and deliver everything to an integrator. The sum of all detailed designs must then cover the architectural design. - -Wan and Wu from the web service team in our example run an OFT convert job like this to pick the parts of the architecture they are affected by: - - oft convert -t AuthenticationProvider,ServiceDiscovery,MapProvider import/arch/ > arch_filtered_by_web_services.xml - -This tells OFT to read all known specification files from the directory "import/arch" and filter by a list of tags. The result is a list of requirements that match the tag filter. - -If you want to also import specification items that do not have any tags, add a single underscore "_" as the first entry in the comma-separated list of tags: - - oft convert -t _,AuthenticationProvider,ServiceDiscovery,MapProvider import/arch/ > arch_filtered_by_web_services.xml - - -### Filtering by Status - -Sometimes you only want to see specification items that have reached a certain maturity level. For example, you might want to create a report that only includes approved requirements. - -To achieve this, you can filter by status using the `-w` or `--wanted-statuses` option: - - oft trace -w approved doc/ - -This tells OFT to only import specification items that have the status `approved`. You can also provide a comma-separated list of statuses: - - oft trace -w approved,proposed doc/ - -### Tracing the Whole Chain - -If you plan to assess the coverage state of your product as a whole, you need to trace the full chain including all artifacts. - -### Tracing the Whole Chain in the Same File System - -Preconditions: - -* All artifacts are readable for the user executing OFT - -Description: - -In a small project you probably have all artifacts in the same file system - most likely under a common root directory. -In this case the easiest way to get a full trace is to list all the directories that OFT should search for artifacts to import. - -Let's assume a typical Java project with the following directory layout: - - /home/git/my-project - |-- doc manuals, requirement specification and design - |-- src - | |-- main - | | '-- java implementation - | '-- test - ... '-- java unit and integration tests - - -In this case the minimal OFT command line looks like this: - -```sh -PROJECT_ROOT='/home/git/my-project/' -oft trace "$PROJECT_ROOT"/doc "$PROJECT_ROOT"/src/main/java "$PROJECT_ROOT"/src/test/java -``` - -Or if you prefer it shorter: - -```sh -cd /home/git/my-project/ -oft trace doc src/main/java src/test/java -``` - -The first variant is better suited for integration into scripts where you usually want to avoid changing the directory. - -By default, this will produce a plain text trace that displays details of all defect specification items and a summary. - -See also: -* [Tracing Options](#tracing-options) for controlling the tracing output - -### HTML Tracing Reports - -While plain text reports are perfect for debugging your tracing chain, sometimes you need reports that are more optically appealing. This is usually true if you have to show reports to management or to quality assessors who usually focus on summaries and statistics rather than detail results. In this case you can tell OFT to create reports in HTML format by adding the `-o html` switch. - -```sh -oft trace -o html -``` - -### Understanding and Fixing Broken Requirement Branches - -Requirements โ€” or specification items as we call them more broadly โ€” in OFT are internally organized in a graph. If you haven't heard of that term, don't worry. In most cases it is close enough to think of the relationships between the specification items like a forest where the highest level of the specification are tree trunks from which details branch out into big branches, twigs and eventually leaves. - -Requirement engineering calls this the "traceability matrix". That term is a bit clunky, but we thought, you should have heard of it at least once. - -#### Everything That can go Wrongโ€ฆ - -What we want to achieve in any role that has to do with requirement engineering is healthy trees with their leaves attached all the way to the trunks. We don't want twigs without leaves, and we definitely don't want leaves lying on the ground. - -Unfortunately, we are only human and humans make mistakes. Here is a non-exhaustive list of typical mistakes that happen when maintaining a traceability matrix: - -| Mistake | How it manifests in OFT | -|---------------------------------|----------------------------------------------------| -| Unimplemented feature | missing leaves in the implementation | -| Missing tests | missing leaves in the test | -| Typos in requirement IDs | causing branches to be cut somewhere in the middle | -| Wrong artifact type in coverage | both missing and unexpected coverage | - -#### Reading and Understanding the Link Error Types - -Depending, from where you look at a specification item, it can have links that point towards it (incoming) or away from it (outgoing). And those links can be broken. This is a typical sign that the requirement matrix contains wrong coverage, is incomplete or has excess parts. - -#### Outgoing Link Statuses - -| Status | Explanation | Ok | -|------------------|------------------------------------------------------------------------|----| -| Covers | This item covers another item | โœ”๏ธ | -| Predated | This item covers a newer revision of another item | โŒ | -| Outdated | This item covers an older revision of another item | โŒ | -| Ambiguous | Two items with the same id are covered by another item | โŒ | -| Unwanted | This item covers another item that does not require this coverage | โŒ | -| Orphaned | This item covers a non-existing item | โŒ | - -"Covers" means everything is fine. - -When the outgoing link from this item is "predated", that means it points to a newer version of the covered item than it should. This is usually a typo that you need to simply fix. On rarer occasion it can hint at a merge error or a problem when multiple teams contribute to the same specification. Check the document history if unsure. - -"Outdated" coverage typically happens when an existing specification item was updated, but the coverage wasn't. This is one of the most useful safeguards in OFT. - -Copy & paste often leads to "ambiguous" coverage, where two items are defined with the same ID. Treat this like you would fix a typo, but be careful, if the ID wasn't updated, then there are likely other copy & paste errors hiding in the vicinity. - -Coverage is "unwanted" when the specification item that it points to didn't ask for it. Check for typos in both IDs. The most common mistake here is that either the required artifact types or the coveraging artifact types are wrong. - -"Orphaned" finally means that this item claims to cover a requirement that does not exist. Or ceased to exist. In this case first check for typos and if it is not a typo, check the history of the documents to see if there is maybe coverage left for something that has been obsoleted higher up in a specification. - - -#### Incoming Link Statuses - -| Status | Explanation | Ok | -|------------------|--------------------------------------------------------------------------|----| -| Covered Shallow | This item is directly covered by another item | โœ”๏ธ | -| Covered Unwanted | This item is covered by another item though it does not require coverage | โŒ | -| Covered Predated | This item is covered by another item that specifies a newer revision | โŒ | -| Covered Outdated | This item is covered by another item that specifies an older revision | โŒ | - -If you see "covered shallow" on an incoming link, this means that there is at least one specification item providing the required coverage. - -"Covered unwanted" means that another item covers the one you are looking at, but it shouldn't, because that coverage was not required. In most cases you are looking at a copy & paste error. Sometimes it is simply a typo the in artifact types. In rarer circumstances this happens the person who wrote the higher level item disagreed with the one who did the coverage. The last variant can be solved by talking to each other. - -"Covered predated" means some other specification item claims to cover a newer version of this item than is currently present in the spec. "Covered outdated" is the opposite situation. The problem resolution is the same as in the [section above](#outgoing-link-statuses) where the predated and outdated incoming links were discussed. - -#### Bidirectional Link Statuses - -| Status | Explanation | Ok | -|------------------|--------------------------------------------------------------------------|----| -| Duplicate | Two items have the same ID | โŒ | - -Duplicate links are special. They don't have a clear direction, since OFT cannot tell which specification item is the original and which one is the duplicate. In either case, you are most likely looking at a copy & past error again. Handle this with care and check if you maybe forgot to adapt other aspects of the copy too, not only the ID. - -## Reference - -### OFT Command Line - -The OFT command line looks like this: - - oft command [option ...] [ ...] - -or - - oft --help - -Where `command` is one of - -* `trace` - create a requirement trace document -* `convert` - convert to a different requirements format -* `help` - display a help message showing the command line usage and version of OFT - -and `option` is one or more of the options listed below. - -#### Display a Short Help Message - -The following commands are equivalent and all display the command line usage and the version of OFT. - - oft -h - oft --help - oft help - -#### Import options - - -a, --wanted-artifact-types [,...] - -Import only specification items where the artifact type matches one of the listed types. - - -w, --wanted-statuses [,...] - -Import only specification items that have a status contained in the comma-separated list of statuses. - - -t, --wanted-tags [_,][,...] - -Import only specification items that have at least one of the listed tags. If you add a single underscore "_" as the first entry in the list, specification items that have no tags at all are also imported. - -#### Tracing options - - -o, --output-format - -The format of the report. - -One of: -* `plain` -* `html` -* `aspec` - -Defaults to `plain`. - - --v, --report-verbosity - -The verbosity of the tracing report. - -* `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 -* `direct_failures` - list of specification items with non-transitive defects -* `failure_summaries` - list of summaries for defect specification items -* `direct_failure_summaries` - list of summaries for specification items with non-transitive defects -* `failure_details` - summaries and details for defect specification items -* `direct_failure_details` - summaries and details for specification items with non-transitive defects -* `overview` - summaries, link details and tags for all specification items, without the description -* `all` - summaries and details for all specification items - -Defaults to `failure_details`. - - --details-section-display - -Initial display status of the details section in the HTML report - -* `collapse` - hide details (default) -* `expand` - show details - -#### Converting Options - - -o, --output-format - -Format into which requirements are converted. - -One of -* `specobject` - -Defaults to `specobject`. - -#### Common Options - - -f, --output-file - -The output file or in case the output consists of more than one file, the output path. Defaults to STDOUT if not given. - - -i, --ignore-artifact-types ...] - -Choose one or more artifact types which are going to be ignored during import. Affects specification items of that type, needed coverage and links to specification items of that type. - - -n, --newline - -Newline format, one of -* `unix` -* `windows` -* `oldmac` - -Defaults to the platform standard if not given. - -You can change the output color scheme. - - -c, --color= - -The available color schemes are - -`black-and-white` -: Plain black and white. On the console this also means no font styles used. - -`monochrome` -: Black, white and shades of grey. Also enables font style on the console. - -`color` -: Color output. Also enables font style on the console. - - - -l, --log-level - -Log level for console logging. One of `OFF`, `SEVERE`, `WARNING`, `INFO`, `CONFIG`, `FINE`, `FINER`, `FINEST`, `ALL`. Defaults to `WARNING`. - -### Build Integration - -In order to integrate requirement tracing with OFT into your CI build, we recommend using the OFT plugins for Maven and Gradle: - -* [openfasttrace-maven-plugin](https://github.com/itsallcode/openfasttrace-maven-plugin) -* [openfasttrace-gradle](https://github.com/itsallcode/openfasttrace-gradle) - -### Input Format Support - -#### Tags in Programming Language or Markup Files - -The Tag Importer is the most basic importer OFT offers. While it supports a wide variety of source formats, it does not -really understand the surrounding format, but instead looks for certain patterns that define specification items. - -To avoid conflict with the formats actual contents, you embed these definitions in comments usually. - -Tags have the following format: - -``` -[ -> ] -``` - -Spaces above were only added for readability. They are optional. In fact usually people prefer a more compact form. -Here is an example of a tag embedded into a Java comment: - -```java -// [impl->dsn~validate-authentication-request~1] -private validate(final AuthenticationRequest request){ - // ... -} -``` - -##### Tags in Markdown and RST Documentation - -Markdown documentation files (`.md` and `.markdown`) and RST files (`.rst`) can cover specification items without being routed through the Tag Importer. Place a full tag in a standalone, single-line native comment: - -```markdown - -``` - -```rst -.. [doc->req~user-guide~1] -``` - -Only complete, standalone Markdown HTML comments and single-line RST comments are recognized. Inline or multi-line comments and RST directives do not import coverage tags. Text outside a native comment that merely resembles a tag is also ignored. - -##### Optional Elements - -Tags can optionally specify a revision number or name and revision number: - -``` -[ ~~ -> ] -[ ~ ~ -> ] -``` - -Examples: - -```java -// [impl~~2->dsn~validate-authentication-request~1] -// [impl~validate-password~2->dsn~validate-authentication-request~1] -``` - -##### Needed Coverage - -When using UML models as design document files like UML models it is useful to add needed coverage as well. To do this, you can use the following format: - -``` -[ -> >> ] -``` - -Example: - -``` -' [dsn->req~1password-login~1>>impl,test] -user -> system : login(token: OAuthToken) -``` - -##### Supported File Extensions - -The Tag Importer recognizes the supported format by the file extension. The following list shows the standard set of -recognized file types: - -**Programming languages** - -* Ada (`.ads`, `.adb`) -* C (`.c`, `.h`) -* C++ (`.C`, `.cpp`, `.c++`, `.cc`, `.H`, `.hpp`, `.h++`, `.hh`) -* C# (`.c#`, `cs`) -* Doxygen (`.dox`) -* Database related (`.sql`, `.pls`) -* Configuration files (`.cfg`, `.conf`, `.ini`) -* [Go](https://golang.org/) (`.go`) -* Groovy (`.groovy`) -* Java (`.java`, `.fxml`) -* JavaScript (`.js`, `.ejs`, `.cjs`, `.mjs`) -* Kotlin (`.kt`, `.kts`) -* Lua (`.lua`) -* Objective C (`.m`, `.mm`) -* Perl (`.pl`, `.pm`) -* PHP (`.php`) -* Protocol Buffers (`.proto`) -* Python (`.py`) -* R (`.r`) -* Rust (`.rs`) -* Shell programming (`.sh`, `.bash`, `.zsh`) -* Swift (`.swift`) -* Terraform (`.tf`, `.tfvars`) -* TypeScript (`.ts`) -* Windows batch files (`.bat`) - -**Configuration and Serialization Formats** - -* JSON (`.json`) -* Protobuf (`.proto`) -* TOML (`.toml`) - -**Markup languages** - -* HTML (`.html`, `.htm`, `.xhtml`) -* YAML (`.yaml`, `.yml`) -* XML (`xml`) - -**Modeling languages** - -* [PlantUML](https://plantuml.com) (`.pu`, `.puml`, `.plantuml`) - -Note that XML is at the moment not yet supported by the Tag Importer, because it would collide with the SpecObj Importer. Once import fallback is implemented, XML will be supported too. - -**Test Specification languages** - -* [Gherkin](https://cucumber.io/docs/gherkin/) (`.feature`) - -#### Gherkin - -OFT imports Gherkin `Scenario` and `Scenario Outline` blocks in `.feature` files when the immediately preceding tag region contains one OFT ID tag. Place optional `Covers` and `Needs` comments after the tags and before the scenario header: - -```gherkin -@smoke -@id:scn~user-can-log-in~1 -# Covers: req~authentication~1 -# Needs: dsn, itest -Scenario: A registered user logs in - Given a registered user - When they enter valid credentials - Then access is granted -``` - -The ID tag becomes the item location and the scenario header becomes its title; executable steps become the description. `Covers` and `Needs` are case-sensitive and optional. Multiple `Covers` comments accumulate coverage IDs, while `Needs` may appear once; all lists must be non-empty and comma-separated. Invalid IDs, types, or directives skip only the affected scenario and emit a warning. - -Existing full coverage tags remain supported in Gherkin comments, for example `# [impl~login~1 -> dsn~authentication~1]`. OFT deliberately ignores coverage-tag-shaped text in executable Gherkin lines. - -#### Markdown - -The main importer of OFT accepts markdown files with the extensions `.md` and `.markdown`. - -#### SpecObject - -Elektrobit's SpecObject format is read from SpecObject files with the `.xml` extension. - -The SpecObject format is extended with support of namespaces to allow adding custom XML elements, e.g.: - -```xml - - - - - - -``` - -## Console Tracing Report - -The Console Tracing Report is the standard report format of OFT. Its main purpose is to quickly debug broken tracing links. In this section you learn how to read this report. - -Below you see a typical example of a requirement from a design document. - - ok [ in: 2 / 2 โœ” | out: 1 / 1 โœ” ] dsn~cli.tracing.default-format~1 (impl, utest) - - The CLI uses plain text as requirement tracing report format if none is given as a parameter. - - [covered shallow ] โ† impl~cli.tracing.default-format-2215031703~0 - [covers ] โ†’ req~cli.tracing.default-output-format~1 - [covered shallow ] โ† utest~cli.tracing.default-format-3750270139~0 - -Let's go through its elements one by one. - -The first line is the summary. - -It starts with the status of the requirement — OK in this case. - -> **ok** [ in: 2 / 2 โœ” | out: 1 / 1 โœ” ] `dsn~cli.tracing.default-format~1` (impl, utest) - -Next we have a couple of numbers. - -The first pair shows how many of the incoming good links this requirement has (two), and how many in total (two). - -> ok [ **in: 2 / 2 โœ”** | out: 1 / 1 โœ” ] `dsn~cli.tracing.default-format~1` (impl, utest) - -Consequently, the next pair informs you how many (one) of the overall (one) outgoing links are good. - -Please note that OFT cannot predict the exact number of required incoming links, because often we are talking about one-to-many relations. So OFT does not try to. The checkmark and crossmark in the square brackets are only a quick indicator of if the existing links are okay. This goes so far that in case of zero links, no mark is displayed at all. - -> ok [ in: 2 / 2 โœ” | **out: 1 / 1 โœ”** ] `dsn~cli.tracing.default-format~1` (impl, utest) - -The [Specification Item ID](#specification-item-id) in the middle is the unique technical ID of this requirement. - -> ok [ in: 2 / 2 โœ” | out: 1 / 1 โœ” ] **dsn****~****cli.tracing.default-format****~****1** (impl, utest) - -In the brackets you find, which artifact types this item expects as coverage. If the type is covered correctly, you see just the name there. - -> ok [ in: 2 / 2 โœ” | out: 1 / 1 โœ” ] `dsn~cli.tracing.default-format~1` (**impl, utest**) - -If it is not covered, the name is lead in by a minus: - -> **not ok** … (**-impl**, utest) - -If an artifact type provides coverage that is not requested, you find this indicated with a plus in front. - -> **not ok** … (impl, **+itest**, utest) - - -If an item is covered correctly, but one of the items it covers has a defect itself, this is called a transitive defect. In this case, the item is marked as `not ok (transitive)`: - -> **not ok (transitive)** … (impl, utest) - -If there were any other specification objects defined with the same ID, you would see the following at the end of the summary line: - -> [has 3 duplicates] - -Everything after that line are details of the requirement. Indented text indicates this. The first part of the details is the description. - - The CLI uses plain text as requirement tracing report format if none is given as a parameter. - -The section with the arrows provides details about incoming and outgoing links. Arrows pointing to the left are incoming links, arrows pointing to the right are outgoing. You can easily remember this, since the arrows either point towards the ID of the connected specification item or away from it. - -The following line means that this design requirement is covered in the implementation. - -> [covered shallow ] โ† `impl~cli.tracing.default-format-2215031703~0` - -The ID of the implementation comes from the Tag Importer and is for its most part auto-generated. The artifact type `dsn` is simply replaced by `impl` here and a number is attached for disambiguation. - -> [covered shallow ] โ† **impl**~cli.tracing.default-format-**2215031703**~0 - -In the square brackets you find the status of the link. - -Just in case you are wondering about the extra spaces in some places of the report, those exist as padding to align multiple similar items in lists. - -### Report Summary - -At the end of the report, a summary is displayed that informs you about the overall state of the trace. - -> **ok** - 123 total - -If there are defects, the summary provides more details: - -> **not ok** - 123 total, 5 direct, 2 transitive defects - -Here, "direct" means that the item itself has a coverage defect, and "transitive" means that the item is correctly covered, but one of the items it covers (or its descendants) has a defect. - -## XML Tracing Report - -Often users want to further process the results generated by OpenFastTrace to create statistics about requirements, -to add the results to a database or further analyze the results. OpenFastTrace therefore provides a reporter that -exports all relevant collected information into a single XML file that can further be processed by other tools. - -The XML exporter is called `aspec` reporter. `aspec` in this case means augmented specobject. An `aspec` report -can be generated by calling OpenFastTrace in the following way: - -```sh -java -jar openfasttrace.jar trace -o aspec -f requirements.xml requirements -``` - -OpenFastTrace needs to be executed with the command `trace` to activate the reporter. The `aspec` report is selected -with that parameter `-o aspec`. `-f` allows to provide the name of the output file into which the XML report is -generated. - -The `aspec` reporter generates an entry per processed requirement: - -* all relevant parameters of the requirement -* information if a requirement is successfully covered by other requirements -* information if all requirements covering a requirement are themselves successfully covered -* list of requirements covering a requirement -* list of requirements linked by a requirement - -The XML output roughly has the following structure - -```xml - - - - arch-my-architecture-requirement - ... - - ... - - ... - -``` - -`` is the toplevel XML element. Beneath the `` one `` entry can be found for -each requirement type found by OpenFastTrace. The element `` contains all requirements matching the type -named in ``. A `` XML tag wraps each requirement. - -A `` entry has the following form: - -```xml - - arch-my-architecture-requirement - 1 - The title - approved - architecture.md - 134 - Yet another architecture - - ... - - - ... - - - ... - - -``` - -`` and `` provide ID and version of the requirement. In OFT terminology the term revision is equal to -version used in the aspec report. `` and `` provide title and description of the requirement. -`` and `` are the name and line number of the original file from which the requirement has been -imported. `` contains more information about the coverage of the requirement and lists other requirements -covering the requirement. - -`` contains requirements that have been marked as dependency. If parts of the information described above is -not available the corresponding XML element is omitted in the generated report. - -The `` XML element has the following form: - -```xml - - - dsn - ... - - COVERED - UNCOVERED - - ... - - - dsn - - - impl - - -``` - -The `` elements provides the following sub elements: - -* ``: List of requirement types that are required to cover the requirement -* ``: `COVERED` if for all needed requirement types another valid requirement covers the requirement. - Valid in this case also means that the covering requirement has status `approved`. - `UNCOVERED` if not all required requirement types covered successfully. -* ``: `COVERED` if all request requirement types are successfully covered by other requirements - that are themselves successfully covered transitively. `UNCOVERED` if the requirement is not successfully covered - transitively. -* ``: The `` element contains a sub element for each covering requirement. -* ``: List of requirement types that are shallow covered. -* ``: List of requirement types that are not shallow covered. - -The element `` describes all covering requirements: - -```xml - - - dsn-requirement - 1 - dsn - COVERED - COVERED - COVERING - - ... - -``` - -The element `` describes each requirement that provides a coverage to the enclosing requirement. Each -covering requirement is described via the element ``. `` and `` provide the requirement -ID and version of the requirement. `` provides the requirement type of the requirement. `` -describes if the covering requirement is shallow covered. A shallowly covered requirement is marked as `COVERED`. -An uncovered requirement is reported as `UNCOVERED`. `` reports a transitive -covered requirement with value `COVERED` and an uncovered requirement with value `UNCOVERED`. If the covering -requirement itself transitively covers the enclosing requirement, `` reports the value `COVERING`. -If the covering requirement does not cover the enclosing requirement `` reports `UNCOVERED`. If the -covering requirement references the enclosing requirement with a wrong version `coveringStatus` reports -`COVERING_WRONG_VERSION`. If the covering requirement is not expected to cover the enclosing requirement (e.g. it has -an unexpected requirement type) the `` is reported as `UNEXPECTED`. - -A requirement described by the XML element `` lists all other requirements that it covers in the element -``: - -```xml - - - arch-requirement - 1 - arch - - ... - -``` - -For each covered requirement `` includes a `` element. A `` lists the referenced -requirement ID with the element ``, the requirement version with `` and the requirement type with the -element ``. - -If a requirement references other requirements without contributing to requirement coverage then all these references -are described by the element ``: - -```xml - - - arch-requirement - 1 - arch - - ... - -``` - -The `` element provides a `` element for each referenced requirement. The -`` element lists requirement ID with the element ``, the requirement version with `` -and the requirement type with the element ``. - -## OFT API - -If you are a software developer planning to integrate OFT into one of your programs or scripts, you will probably want to use the OFT API. - -Below you find a few short examples of how to use the OFT API. For details check the JavaDoc documentation of the interface [org.itsallcode.openfasttrace.core.Oft](../../core/src/main/java/org/itsallcode/openfasttrace/core/Oft.java) in the source code. - -### Using OFT From Java - -The Java interface uses the "fluent programming" paradigm to make the code more compact and easy to read. - -The steps that you need to program using the OFT API depend on whether you want to covert between requirement formats - - import -> export - -or run a report. - - import -> link -> trace -> report - -#### Converting File from Java - -The following example code use OFT as a converter that scans the current working directory recursively (default import setting) and exports the found artifacts with the standard settings to a ReqM2 file. - -```java -import org.itsallcode.openfasttrace.Oft; -import org.itsallcode.openfasttrace.core.SpecificationItem; -``` - -Select input paths and import specification items from there: - -```java -final Oft oft = Oft.create(); -final List items = oft.importItems(settings); -``` - -Export the items: - -```java -oft.exportToPath(items, Paths.get("/output/path/export.oreqm")); -``` - -#### Tracing and Reporting From Java - -The example below shows how to use OFT as a reporter. - -```java -import org.itsallcode.openfasttrace.Oft; -import org.itsallcode.openfasttrace.core.LinkedSpecificationItem; -import org.itsallcode.openfasttrace.core.SpecificationItem; -import org.itsallcode.openfasttrace.core.Trace; -``` - -The import is similar to the converter case, except this time we add an input path explicitly for the sake of demonstration: - -```java -final ImportSettings settings = ImportSettings // - .builder() // - .addInputs("/input/path") // - .build; -final Oft oft = Oft.create(); -final List items = oft.importItems(settings); -``` - -Now link the items together (i.e. make them navigable): - -```java -final List linkedItems = oft.link(items); -``` - -Run the tracer on the linked items: - -```java -final Trace trace = oft.trace(linkedItems); -``` - -Create a report from the trace: - -```java -oft.reportToStdOut(trace); -``` - -You can also use the trace results in your own code: - -```java -if (trace.hasNoDefects()) -{ - // ... do something -} -``` - -#### Reporting Formats - -There are various reporting formats for OFT and one can set it using the ReportSettings object. - -```java -ReportSettings reportSettings = ReportSettings.builder().outputFormat("html").build(); -``` - -The `ReportSettings` builder has other functions as well that allow you to set verbosity etc. - -OFT allows you to report directly to the standard output or to a file - -```java -// Reporting to a file -oft.reportToPath(trace, reportPath, reportSettings); -``` - -```java -// Reporting to stdout -oft.reportToStdOut(trace); -``` - -#### Configuring the Steps - -Import, export and report each have an overloaded variant that can be configured using the following classes - -* [org.itsallcode.openfasttrace.api.importer.ImportSettings](../../api/src/main/java/org/itsallcode/openfasttrace/api/importer/ImportSettings.java) -* [org.itsallcode.openfasttrace.core.ExportSettings](../../core/src/main/java/org/itsallcode/openfasttrace/core/ExportSettings.java) -* [org.itsallcode.openfasttrace.api.ReportSettings](../../api/src/main/java/org/itsallcode/openfasttrace/api/ReportSettings.java) - -Each of those classes comes with a builder which is called like this: - -```java -ReportSettings settings = ReportSettings.builder().newline(Newline.UNIX).build(); -``` - -### Exit Codes - -The OFT command line interface returns the following exit codes: - -* `0` on success -* `1` on OFT error -* `2` on command line error - -## Tool Support - -### Tools for Authoring OFT Documents - -The following editors and integrated development environments are well suited for authoring OFT documents. The list is not exhaustive, any editor with Markdown capabilities can be used. - -| Editor / IDE | Syntax
highlighting | Preview | Outline | HTML
export | OFT
Plugin | -|------------------------------------------------------|:-----------------------:|:-------:|:-------:|:---------------:|:--------------:| -| [CLion](https://www.jetbrains.com/clion/) | y | y | y | y | y | -| [Gedit](https://wiki.gnome.org/Apps/Gedit) | y | | | | | -| [Eclipse](https://eclipse.org) | y | y | y | y | y | -| [IntelliJ](https://www.jetbrains.com/idea/) | y | y | y | y | | -| [PyCharm](https://www.jetbrains.com/pycharm/) | y | | | | y | -| [Vim](https://www.vim.org/) | y | | | | | -| [Visual Studio Code](https://code.visualstudio.com/) | y | y | y | y | | - -Please note that some IDEs may require additional plugins to support Markdown features. - -#### IDE Plugins - -We offer plugins for the following popular IDEs. - -* [JetBrains IDEs (CLion, PyCharm, IntelliJ, etc.)](https://github.com/itsallcode/openfasttrace-intellij-plugin) - -Typical features include: - -* Syntax highlighting for OFT specification item IDs -* Symbol search for OFT specification items -* Navigation between OFT specification items -* Templates for OFT specification items -* Run configurations for OFT traces -* In-IDE trace report - -### Templates for IDEs - -You can create OpenFastTrace artifacts faster with templates for your IDE. See [the list of available IDE Templates](https://github.com/itsallcode/openfasttrace-ide-templates). +## [Introduction](introduction/introduction.md) +* [Who Should Read This Document?](introduction/who_should_read_this_document.md) +* [What is Requirement Tracing?](introduction/what_is_requirement_tracing.md) +* [Why do I Need Requirement Tracing?](introduction/why_do_i_need_requirement_tracing.md) +* [Concepts and Terms](introduction/concepts_and_terms.md) + +## [Installation](installation/installation.md) +* [Linux Installation](installation/linux.md) +* [macOS Installation](installation/macos.md) +* [Windows Installation](installation/windows.md) + +## [Use Cases](use_cases/use_cases.md) +* [Writing a Specification](use_cases/writing_a_specification.md) +* [Excluding Parts of a Specification Document for OFT Parsing](use_cases/excluding_parts_of_a_specification_document_for_oft_parsing.md) +* [Delegating Requirement Coverage](use_cases/delegating_requirement_coverage.md) +* [Distributing the Detailing Work](use_cases/distributing_the_detailing_work.md) +* [Filtering by Status](use_cases/filtering_by_status.md) +* [Tracing the Whole Chain](use_cases/tracing_the_whole_chain.md) +* [Tracing the Whole Chain in the Same File System](use_cases/tracing_the_whole_chain_in_the_same_file_system.md) +* [HTML Tracing Reports](use_cases/html_tracing_reports.md) +* [Understanding and Fixing Broken Requirement Branches](use_cases/understanding_and_fixing_broken_requirement_branches.md) + +## [Reference](reference/reference.md) +* [OFT Command Line](reference/oft_command_line.md) +* [Build Integration](reference/build_integration.md) +* [Input Format Support](reference/input_format_support.md) +* [Console Tracing Report](reference/console_tracing_report.md) +* [Report Summary](reference/report_summary.md) +* [XML Tracing Report](reference/xml_tracing_report.md) + +## [OFT API](oft_api/oft_api.md) +* [Using OFT From Java](oft_api/using_oft_from_java.md) +* [Exit Codes](oft_api/exit_codes.md) + +## [Tool Support](tool_support/tool_support.md) +* [Tools for Authoring OFT Documents](tool_support/tools_for_authoring_oft_documents.md) +* [Templates for IDEs](tool_support/templates_for_ides.md) + +## [Product Lifecycle](product_lifecycle/product_lifecycle.md)