From 16b11650549a7b98c5b7f4404578ebfb7a0dc4ca Mon Sep 17 00:00:00 2001 From: redcatbaer Date: Thu, 8 Oct 2026 17:16:37 +0200 Subject: [PATCH] #613: Added terminating specification item example to user guide. --- doc/terminology.md | 11 +++- .../distributing_the_detailing_work.md | 5 +- .../use_cases/filtering_by_status.md | 3 +- .../use_cases/html_tracing_reports.md | 3 +- .../partial_tracing_by_responsibility.md | 56 +++++++++++++++++++ .../use_cases/tracing_the_whole_chain.md | 3 +- ...the_whole_chain_in_the_same_file_system.md | 3 +- ..._and_fixing_broken_requirement_branches.md | 3 +- doc/user_guide/use_cases/use_cases.md | 2 +- 9 files changed, 73 insertions(+), 16 deletions(-) create mode 100644 doc/user_guide/use_cases/partial_tracing_by_responsibility.md diff --git a/doc/terminology.md b/doc/terminology.md index c118a5ba..2d039f94 100644 --- a/doc/terminology.md +++ b/doc/terminology.md @@ -1,5 +1,4 @@ --- -layout: default title: Terminology nav_order: 5 --- @@ -86,7 +85,7 @@ The atomic unit of a specification, representing a requirement, design decision, 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). +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. @@ -109,6 +108,14 @@ Label for categorizing [specification items](#specification-item), used for filt ### Terminating Specification Item A [specification item](#specification-item) that does not require further coverage (e.g., code, tests). +Example: + +``` +"feat" ──needs──> "req" ──needs──> "dsn" ──needs──> "impl" (terminates chain) + ├────> "utest" (terminates chain) + ╰────> "itest" (terminates chain) +``` + ### Transitive Defect Coverage gap caused by an [undercovered](#undercovered) [provider](#coverage-provider) in the trace chain. diff --git a/doc/user_guide/use_cases/distributing_the_detailing_work.md b/doc/user_guide/use_cases/distributing_the_detailing_work.md index dbd214d2..702c791a 100644 --- a/doc/user_guide/use_cases/distributing_the_detailing_work.md +++ b/doc/user_guide/use_cases/distributing_the_detailing_work.md @@ -1,9 +1,8 @@ --- -layout: default title: Distributing the Detailing Work parent: Use Cases grand_parent: User Guide -nav_order: 4 +nav_order: 5 --- ### Distributing the Detailing Work @@ -36,4 +35,4 @@ This tells OFT to read all known specification files from the directory "import/ 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 + oft convert -t _,AuthenticationProvider,ServiceDiscovery,MapProvider import/arch/ > arch_filtered_by_web_services.xml \ No newline at end of file diff --git a/doc/user_guide/use_cases/filtering_by_status.md b/doc/user_guide/use_cases/filtering_by_status.md index 03dafcc2..c686148d 100644 --- a/doc/user_guide/use_cases/filtering_by_status.md +++ b/doc/user_guide/use_cases/filtering_by_status.md @@ -1,9 +1,8 @@ --- -layout: default title: Filtering by Status parent: Use Cases grand_parent: User Guide -nav_order: 5 +nav_order: 6 --- ### Filtering by Status diff --git a/doc/user_guide/use_cases/html_tracing_reports.md b/doc/user_guide/use_cases/html_tracing_reports.md index 2555154d..bf6b32d3 100644 --- a/doc/user_guide/use_cases/html_tracing_reports.md +++ b/doc/user_guide/use_cases/html_tracing_reports.md @@ -1,9 +1,8 @@ --- -layout: default title: HTML Tracing Reports parent: Use Cases grand_parent: User Guide -nav_order: 8 +nav_order: 9 --- ### HTML Tracing Reports diff --git a/doc/user_guide/use_cases/partial_tracing_by_responsibility.md b/doc/user_guide/use_cases/partial_tracing_by_responsibility.md new file mode 100644 index 00000000..9c757841 --- /dev/null +++ b/doc/user_guide/use_cases/partial_tracing_by_responsibility.md @@ -0,0 +1,56 @@ +--- +layout: default +title: Partial Tracing by Responsibility +parent: Use Cases +grand_parent: User Guide +nav_order: 4 +--- + +### Partial Tracing by Responsibility + +In a software project, different roles are responsible for different layers of the traceability chain. Product owners work with features (`feat`) and requirements (`req`), architects with architecture and detailed design (`arch`, `dsn`), developers with implementation and unit tests (`impl`, `utest`), and test engineers with integration and system tests (`itest`, `stest`). + +When Soeren, the product owner, adds a feature and its system requirements, a full trace could report missing design or implementation that is not part of his review. Andrea, the architect, can likewise check design coverage before development is complete. The artifact type filter lets each role trace the layers relevant to their work. + +For example, the layers may be organized like this: + +```text +[Product owner] feat ──> req +[Architect] └──> arch ──> dsn +[Developer] └──> impl, utest +[Test engineers] └──> itest, stest +``` + +Each level declares the artifact types needed to cover its specification items (`Needs: ...`). + +Use the `-a` or `--wanted-artifact-types` option with a comma-separated list of [artifact types](../../terminology.md#artifact-type) to limit a trace. Items, coverage needs, and links for types outside the list are left out of the trace; the filter narrows the trace results, not the files parsed. + +Soeren, the product owner, checks that each user feature (`feat`) is specified by system requirements (`req`): + + oft trace -a feat,req doc/ + +This checks feature-to-requirement coverage without reporting missing downstream design or implementation. + +After the requirements are in place, Andrea, the architect, checks their coverage by architecture and detailed design: + + oft trace -a feat,req,arch,dsn doc/ + +Including both feature and requirement items keeps the earlier layer in the trace; the filter does not require implementation or tests yet. + +Wan and Wu, the developers, check implementation and unit tests along with the preceding specifications: + + oft trace -a feat,req,arch,dsn,impl,utest doc/ src/ + +When integration and system tests are ready, test engineers include their types in the filter: + + oft trace -a feat,req,arch,dsn,impl,utest,itest,stest doc/ src/ + +#### Artificial Termination of Specification Items + +In a full trace, a chain ends at [terminating specification items](../../terminology.md#terminating-specification-item)—items that do not require further coverage (such as source code or test markers without a `Needs:` declaration). + +When you trace with an artifact type filter, OFT strips all coverage requirements for artifact types that are not in the filter list. For instance, when Soeren runs `oft trace -a feat,req doc/`, a system requirement that normally declares `Needs: arch` has its `arch` requirement removed during the trace. This *artificially terminates* the requirement items at the boundary of the selected artifact types, allowing the trace to pass without missing-coverage errors for downstream artifacts that have not yet been written. + +See also: +* [Distributing the Detailing Work](distributing_the_detailing_work.md) for filtering by tags across multiple teams +* [Import Options](../reference/oft_command_line.md#import-options) for command-line syntax details diff --git a/doc/user_guide/use_cases/tracing_the_whole_chain.md b/doc/user_guide/use_cases/tracing_the_whole_chain.md index dc943b66..97e6e404 100644 --- a/doc/user_guide/use_cases/tracing_the_whole_chain.md +++ b/doc/user_guide/use_cases/tracing_the_whole_chain.md @@ -1,9 +1,8 @@ --- -layout: default title: Tracing the Whole Chain parent: Use Cases grand_parent: User Guide -nav_order: 6 +nav_order: 7 --- ### Tracing the Whole Chain 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 index f6b6392a..6a416972 100644 --- 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 @@ -1,9 +1,8 @@ --- -layout: default title: Tracing the Whole Chain in the Same File System parent: Use Cases grand_parent: User Guide -nav_order: 7 +nav_order: 8 --- ### Tracing the Whole Chain in the Same File System 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 index f3725770..1e624712 100644 --- 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 @@ -1,9 +1,8 @@ --- -layout: default title: Understanding and Fixing Broken Requirement Branches parent: Use Cases grand_parent: User Guide -nav_order: 9 +nav_order: 10 --- ### Understanding and Fixing Broken Requirement Branches diff --git a/doc/user_guide/use_cases/use_cases.md b/doc/user_guide/use_cases/use_cases.md index 6c589392..182ea42f 100644 --- a/doc/user_guide/use_cases/use_cases.md +++ b/doc/user_guide/use_cases/use_cases.md @@ -1,5 +1,4 @@ --- -layout: default title: Use Cases parent: User Guide has_children: true @@ -14,6 +13,7 @@ The following use cases describe common tasks and workflows when using OpenFastT * **[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. +* **[Partial Tracing by Responsibility](partial_tracing_by_responsibility.md)**: Filter by artifact types to verify requirement coverage layer by layer according to team roles and responsibilities. * **[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.