3 unstable releases
0.2.14 | Sep 21, 2023 |
---|---|
0.2.12 | Sep 13, 2023 |
0.1.0 | Aug 23, 2023 |
#145 in Testing
54 downloads per month
135KB
2.5K
SLoC
mantra
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.
Core Concepts
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:
# my_req_id: Some requirement title
**References:**
- in branch main: 3
- in branch stable: 1
Requirement Structure
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:
# my_req_id: Some requirement title
A high-level requirement.
## my_req_id.sub_req_id: Some sub-requirement title
A low-level requirement of `my_req_id`.
Referencing
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:
/// This function does something.
///
/// [req:req_id]
fn my_function() {
//...
}
Multiple repositories
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:**
- in repo frontend_repo in branch main: 3
- in repo backend_repo in branch main: 1
Usage
Setup
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:
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.
Commands
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 wikimantra check ./requirements_folder ./project_folder
Possible output:
-------------------------------------------------------------------- `mantra check` ran successfully for branch: main **Checks:** - All references refer to existing requirements - No deprecated requirement referenced - No duplicate requirement IDs in wiki - 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:
***Active* requirements in release v0.2.10:** - check: Validate wiki and references - check.ci: Add check overview as PR comment - filter: Use ignore files to restrict the search for references - qa: Quality Assurance - qa.DoD: Have a "Definition of Done" for requirements - qa.pipeline: Pipeline to ensure a high library quality - qa.pipeline.1_style: Ensure consistent formatting - qa.pipeline.2_lint: Ensure good coding standard - qa.pipeline.3_build: Ensure *evident* builds - qa.pipeline.4_tests: Ensure tests still pass - qa.sustain: Consider sustainability during design and development - qa.tracing: Use requirement IDs in [mantra](https://github.com/mhatzl/mantra) - ref_req: Reference requirements - ref_req.ignore: Ignore requirement references - ref_req.test: Test requirement referencing - release: Release report - release.checklist: Checklist for requirements marked with *manual* flag - req_id: Requirement ID - req_id.sub_req_id: Sub-requirements for high-level requirements - status: Show wiki status - status.branch: See status for one branch in the wiki - status.cmp: Compare status of two branches in the wiki - sync: Synchronize wiki, implementation, and tests - sync.ci: CI support for *mantra sync* - wiki: Documentation for requirements - wiki.ref_list: *References* list - wiki.ref_list.branch_link: Link to branches - wiki.ref_list.deprecated: Mark requirements as *deprecated* in specific branches - wiki.ref_list.manual: Mark requirements to require manual verification - wiki.ref_list.repo: Handle multiple repositories for one wiki 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:
**Wiki status for branch `main`:** - 1 requirement is *ready* to be implemented - 30 requirements are *active* - 0 requirements are *deprecated* - 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 phaseCompare branches:
It is possible to compare two branches using the
status
command.mantra status --branch=main --cmp-branch=stable ./requirements_folder
Possible output:
**Wiki differences between `main` and `stable`:** | 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.
CI/CD
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:
- mantra_pr.yml ... Uses
check
to create a comment in PR conversations - mantra.yml ... Uses
sync
to synchronize references between wiki and project - release-please.yml ... Uses
release
to add a release report to a created release
Skip content for the reference search
Files 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]
License
MIT Licensed
Dependencies
~6–15MB
~182K SLoC