Reqtraq is an open source Go tool for requirement management. Reqtraq is designed to stay out of your way. It requires no user interaction for day-to-day tasks. Instead, it parses documents that are required in the certification process and extracts everything it needs from there.
Reqtraq has two main use-cases:
-
Git hook makes sure the documents have the correct structure and linking:
- Files correctly named
- Requirements correctly formatted and continuous
- References exist, Parent requirements exist and not DELETED
- Required attributes are there and correctly formatted
-
Standalone binary
- Report generation with filtering
- Web tool for easy inspection
- go 1.17+
- pandoc
- universal-ctags Note there is also the unmaintained exuberant-ctags which should be avoided.
- clang+llvm-14, only needed for building reqtraq with support for libclang.
Basic installation can be done with:
$ go install github.com/daedaleanai/reqtraq@latest
$ export PATH=$PATH:$GOPATH/bin
For repos having requirements documents defined in reqtraq_config.json with "codeParser": "clang" reqtraq needs libclang support. Install the libclang-14-dev package on Ubuntu, or download clang+llvm-14 from their release page and unpack it somewhere. Set LLVM_LIB accordingly and build reqtraq enabling the "clang" tag:
$ LLVM_LIB=/usr/lib/llvm-14/lib
$ LLVM_LIB=~/clang+llvm-14.0.0-x86_64-linux-gnu-ubuntu-18.04/lib
$ export CGO_LDFLAGS="-L${LLVM_LIB} -Wl,-rpath=${LLVM_LIB}"
$ go install --tags clang github.com/daedaleanai/reqtraq@latest
$ export PATH=$PATH:$GOPATH/bin
Reqtraq is tightly integrated with Git. See the certification documents in the certdocs directory for some good examples.
Reqtraq uses the Git history to figure out the Git commits associated with a requirement and the Phabricator API to assess the completion status of each requirement.
$ reqtraq nextid certdocs/TEST-138-SDD.md
REQ-TEST-SWL-21
$ reqtraq list certdocs/TEST-100-ORD.md
Requirement REQ-TEST-SYS-1 Bidirectional tracing.
...
In report tags such as 'Changelists' and 'Problem Reports' will not work if not integrated with a task manager such as Phrabricator etc. (currently supported for Phabricator; JIRA and others need to be added)
$ reqtraq report down
2017/06/06 22:48:12 Creating ./req-down.html (this may take a while)...
...
Filtering:
$ reqtraq report down --id_filter=".*TEST-SYS.*"
2017/06/06 22:51:23 Creating ./req-down.html (this may take a while)...
2017/06/06 22:51:41 Creating ./req-down-filtered.html (this may take a while)...
$ reqtraq web :8080
Server started on http://localhost:8080
Reqtraq is configured using a reqtraq_config.json file in the root of the repository that contains both requirements and data.
{
"repoName": "reqtraq",
"commonAttributes": [
{
"name": "Rationale",
"required": "any"
},
{
"name": "Verification",
"value": "(Demonstration|Unit [Tt]est|[Tt]est)"
}
],
"documents": [
{
"path": "certdocs/TRAQ-100-ORD.md",
"prefix": "TRAQ",
"level": "SYS",
},
{
"path": "certdocs/TRAQ-137-SRD.md",
"prefix": "TRAQ",
"level": "SWH",
"parent": {
"prefix": "TRAQ",
"level": "SYS"
}
},
{
"path": "certdocs/TRAQ-138-SDD.md",
"prefix": "TRAQ",
"level": "SWL",
"parent": {
"prefix": "TRAQ",
"level": "SWH"
},
"implementation": [
{
"archs": {
"armv6m": {
"compilationDatabase": "",
"compilerArguments": ["--target=thumbv6m-linux-eabi"]
},
"linux-x64": {
"compilationDatabase": "/BUILD/OUTPUT/compile_commands.json",
"compilerArguments": []
}
},
"code": {
"paths": ["."],
"matchingPattern": ".*\\.go$",
"ignoredPatterns": [".*_test\\.go$"],
"archPatterns": {
"armv6m": {
"paths": ["src", "include"],
"matchingPattern": ".*/armv6m/.*((.*\\.cc$)|(.*\\.c$)|(.*\\.hh$))",
"ignoredPatterns": [".*_test\\.cc$"]
},
"linux-x64": {
"paths": ["src", "include"],
"matchingPattern": ".*/linux-x64/.*((.*\\.cc$)|(.*\\.c$)|(.*\\.hh$))",
"ignoredPatterns": [".*_test\\.cc$"]
}
}
},
"tests": {
"paths": ["."],
"matchingPattern": ".*_test\\.go$",
"archPatterns": {
"armv6m": {
"paths": ["src"],
"matchingPattern": ".*/armv6m/.*_test\\.cc$"
},
"linux-x64": {
"paths": ["src"],
"matchingPattern": ".*/linux-x64/.*_test\\.cc$"
}
}
}
}
]
}
]
}All document paths are specified with respect to the root of the repository they belong to. It is possible to separate code and requirements across multiple repositories with reqtraq by specifying parent and children repositories in its configuration file.
There must always be a top level repository that contains a configuration file with no parents.
Child repository configuration:
{
"repoName": "childRepo",
"parentRepository": {
"repoName": "parentRepo",
"repoUrl": "/path/to/parent/repo"
},
"documents": [
{
"path": "certdocs/TEST-138-SDD.md",
"prefix": "TRAQ",
"level": "SWL",
"parent": {
"prefix": "TRAQ",
"level": "SWH"
},
"attributes": [
{
"name": "Parents",
"required": "any",
"value": "REQ-TEST-SWH-(\\d+)"
}
],
"implementation": [
{
"archs": {
"armv6m": {
"compilationDatabase": "",
"compilerArguments": ["--target=thumbv6m-linux-eabi"]
},
"linux-x64": {
"compilationDatabase": "/BUILD/OUTPUT/compile_commands.json",
"compilerArguments": []
}
},
"code": {
"paths": ["code"],
"matchingPattern": ".*\\.(cc|c|h|hh)$",
"ignoredPatterns": [".*_test\\.(cc|c|h|hh)$"],
"archPatterns": {
"armv6m": {
"paths": ["src", "include"],
"matchingPattern": ".*/armv6m/.*((.*\\.cc$)|(.*\\.c$)|(.*\\.hh$))",
"ignoredPatterns": [".*_test\\.cc$"]
},
"linux-x64": {
"paths": ["src", "include"],
"matchingPattern": ".*/linux-x64/.*((.*\\.cc$)|(.*\\.c$)|(.*\\.hh$))",
"ignoredPatterns": [".*_test\\.cc$"]
}
}
},
"tests": {
"paths": ["."],
"matchingPattern": ".*_test\\.(cc|c|h|hh)$",
"ignoredPatterns": [],
"archPatterns": {
"armv6m": {
"paths": ["src"],
"matchingPattern": ".*/armv6m/.*_test\\.cc$"
},
"linux-x64": {
"paths": ["src"],
"matchingPattern": ".*/linux-x64/.*_test\\.cc$"
}
}
}
}
]
}
]
}Parent repository configuration:
{
"repoName": "parentRepo",
"childrenRepositories": [
{
"repoName": "childRepo",
"repoUrl": "/path/to/child/repo"
},
{
"repoName": "anotherChildRepo",
"repoUrl": "/path/to/another/child/repo"
}
],
"commonAttributes": [
{
"name": "Rationale",
"required": "any"
},
{
"name": "Verification",
"value": "(Demonstration|Unit [Tt]est|[Tt]est)"
}
],
"documents": [
{
"path": "certdocs/TEST-100-ORD.md",
"prefix": "TRAQ",
"level": "SYS",
"attributes": []
},
{
"path": "certdocs/TEST-137-SRD.md",
"prefix": "TRAQ",
"level": "SWH",
"parent": {
"prefix": "TRAQ",
"level": "SYS"
}
}
]
}Accepted references to parent and child repositories are:
- A file system path which contains a git checkout.
- A URL to a git repository.
$ reqtraq help
Shows general help and a list of commands
$ reqtraq help <command>
Displays help on a specific command.