Req Toolkit
ReqTk is a requirements management toolkit built around a human-readable, git-friendly .req file format. Define, validate, format, trace, transform, and convert requirements directly from your repository.
⚠️Experimental!
ReqTk is still under development and is missing some critical tests. Data loss is possible. Keep backups and report bugs.
VSCode extension is coming soon!
Design goals
- Human readable (good git-diffs)
- Hierarchical structure
- Possibility for custom attributes (e.g. multiple-languages, tags, etc.)
- IDE support possibility
- AI friendly (e.g. tooling to search requirements)
- Conversion from existing requirement formats
- Easy way to publish for open-source projects (markdown conversion)
- Tracing (to other requirements, to tests, to issues)
- CI support (format, check)
- History (from git)
Getting started
- Install
cargo(instructions) - Run
cargo install reqtk - Navigate to your project's root directory.
- Run
reqtk init- This will create
reqtk.jsonandrequirements.req. - Adjust the source and requirement file paths to your needs.
- This will create
init will generate the following req file:
[id-type=incremental]
[id-prefix=REQ-]
[id-count=2]
@REQ-1(My requirement) {
[type=functional]
[description]
Hello world!
[/description]
}
Generate markdown
You can generate markdown from your requirements using:
reqtk convert -o REQUIREMENTS.md
Reflow ids in your requirement file
Before first commit you might want to re-assign the ids in your docment incrementally using:
reqtk transform --id incremental --prefix MYREQ-
ReqTk usage
ReqTk is a requirements management toolkit built around a human-readable, git-friendly `.req` file format.
Usage: reqtk [OPTIONS] <COMMAND>
Commands:
format Format req files
check Analyze req files for issues
convert Convert between known requirement formats (req, json)
transform Transform a req file (e.g. reflow ids, minify)
tokenize Tokenize a req file (output: JSON)
trace Find traces for requirements (output: JSON)
find Finds a single requirement (output: JSON)
init Initializes a reqtk.json workspace file
help Print this message or the help of the given subcommand(s)
Options:
-r, --report <REPORT> Issue reporting format [default: human] [possible values: human, json]
-v, --verbose Enable verbose output
-h, --help Print help
-V, --version Print version
Input location ([INPUTS]):
MISSING → inputs from nearest 'reqtk.json' workspace file
PATH → use the given files
reqtk.json → load files from the provided workspace file
- → stdin
Output location (-o, --output):
MISSING → output to default location
(same as input, extension is changed to match the output format)
e.g. file.req → file.tokens.json, stdin → stdout
PATH → output location (only when one input is provided)
- → stdout
REQ file format
Req file elements
Attributes
Single line attribute:
[key=value]
Multi-line attribute:
[key]
multi
line
value
[/key]
Attributes can be placed at root level or inside other elements (see later).
Root level attributes:
| key | type | notes |
|---|---|---|
| id-type | incremental, incremental-N, random, random-N, where N is an integer |
Type of the requirement IDs. Used by IDE's to generate the identifiers for new requirements. |
| id-prefix | string | Prefix of the requirement IDs. Type of the requirement IDs. Used by IDE's to generate the identifiers for new requirements. |
| id-count | unsigned integer | Only used when id-type=incremental*. Contains the counter for incremental requirement IDs. Used by IDE's to generate the identifiers for new requirements. |
Requirement types
You can define your own requirement types with the following syntax (root level):
$custom(Custom) {
[icon=star]
[color=yellow]
[has-children=true]
}
Requirement type attributes:
| key | type | notes |
|---|---|---|
| icon | material icon | Icon of the requirement type. |
| color | html/css color | Color of the icon. |
| has-children | true/false |
Allow the IDE to add children to the requirement. |
The following requirement types are built-in:
| icon | id | title | has-children | notes |
|---|---|---|---|---|
| folder | Folder | true | (default) | |
| functional | Functional | false | ||
| informative | Informative | false | ||
| parameter | Parameter | false | ||
| limitation | Limitation | false |
Requirements
You can add requirements with the following syntax:
@parent(Parent) {
@child(Child) {
[type=functional]
[description]
Hello world!
[/description]
}
}
Requirement attributes:
| key | type | notes |
|---|---|---|
| type | folder (default), functional, informative, parameter, limitation or the identifier of a custom requirement type |
Requirement type. |
| description | markdown text | Requirement description. |
The requirement description supports references to other requirements in the following format:
@REQ-1(First) {
[type=functional]
[description]
This is a reference to {@REQ-2}
[/description]
}
@REQ-2(Second) {
[type=functional]
[description]
This is a reference to {@REQ-1}
[/description]
}
The traces will show up in the reqtk trace command.