Manuels ANforderungs-TRAcing
mantra is a tool for easier tracing between requirements, implementation, and tests.
Checkout the requirements section in mantra's wiki to see how requirement tracing with mantra looks.
To use mantra, a system/project must document requirements in a way that allows automatic edits at a textual level. Wikis are a good way to achieve this, and most project management tools offer at least a lightweight wiki. mantra is primarily built to work together with the structure of the wiki-repo-template for GitHub wikis, but it should be relatively simple to adapt other wikis to use mantra.
Human-readable IDs are used to identify requirements, and reference them in the implementation and/or tests. These requirement IDs must be set manually on the implementation and test side. mantra then adds the number of references a requirement has on the implementation and test side to the wiki. Since systems/projects may have different branches, these numbers are linked to the branch mantra is run against.
Example:
```
References:
Every requirement must have a heading starting with a unique requirement ID followed by : and a title.
A requirement hierarchy may be used to create a structure of high and low-level requirements.
Example:
```
A high-level requirement.
A low-level requirement of my_req_id.
```
Requirement IDs may be referenced in the implementation and/or tests of your system/project using the syntax [req:req_id].\
This syntax should be independent enough in most programming languages that mantra can distinguish an expression from a requirement reference.
Example:
rust
/// This function does something.
///
/// [req:req_id]
fn my_function() {
//...
}
A system/project may have multiple repositories, but only one wiki to manage requirements. Therefore, mantra offers options to set the name of a repository in addition to the branch name. The repository name is then added to the entry in the references list.
Note: It is not possible to reference multiple wikis, because requirements should be kept in one place.
Example:
``` References:
mantra is available on crates.io, and may be installed using the Rust toolchain:
cargo install mantra
Alternatively, mantra is available as Docker image, and may be run locally with:
docker run manuelhatzl/mantra:main mantra
To use the Docker image inside GitHub workflows, use:
yaml
runs-on: ubuntu-latest
container:
image: manuelhatzl/mantra:main
Note: The image is based on the Alpine image, and may not support all commands available with the Ubuntu image.
mantra is primarily a command line tool that offers various commands.\
Use mantra <command> --help to see all available options per command.
mantra currently offers the following commands:
check ... Used to check if the wiki structure is valid, and all references refer to requirements in the wiki
mantra check ./requirements_folder ./project_folder
Possible output:
```md
mantra check ran successfully for branch: main
Checks:
All entries in references lists are valid
Increased direct references for 1 requirement:
req:wiki.ref_list.repo references: 6 -> 9
Took: 87ms ```
Note: This command outputs all found errors before the summary shown above.
release ... Used to create release reports to list all active requirementsmantra release --release-tag=v0.2.10 ./requirements_folder
Possible output:
```md Active requirements in release v0.2.10:
check: Validate wiki and references
wiki: Documentation for requirements
Took: 40ms ```
Note: The option --checklist may be set to create a checklist for all requirements that require manual verification.
status ... Shows the current state of the wikimantra status --detail-ready ./requirements_folder
Possible output:
``md
**Wiki status for branchmain`:**
1 requirement is ready to be implemented
0 requirements need manual verification
Ready requirements:
qa.ux: Experience using mantra
Took: 34ms ```
Note: The --detail-<phase> options may be used to list requirement IDs that are in this phase
Compare branches:
It is possible to compare two branches using the status command.
mantra status --branch=main --cmp-branch=stable ./requirements_folder
Possible output:
``md
**Wiki differences betweenmainandstable`:**
| REQ-ID | main | stable |
| -------------- | ---------- | ------ |
| ref_req.test | deprecated | active |
```
sync ... Used to synchronize reference counter between wiki and projectmantra sync ./requirements_folder ./project_folder
Note: This command stops at the first encountered error. You may want to use mantra check to get all errors at once.
For better automation, some commands may be used in CI/CD pipelines.
A docker image is available at manuelhatzl/mantra for easier integration.
The image exposes mantra without any predefined command, so it may be used like an installed command line tool.
This repository itself uses mantra in the following GitHub workflows:
check to create a comment in PR conversationssync to synchronize references between wiki and projectrelease to add a release report to a created releaseFiles and folders may be ignored for the references search, by adding them to .gitignore or .mantraignore files.
These files and folders are then skipped when searching references in the project.
It is also possible to ignore only the next reference inside a file, by setting [mantra:ignore_next] directly before the reference.
Example:
[mantra:ignore_next]
[req:ignored_req]
MIT Licensed