Requirements
Requirements capture what the JabRef should do. Regard it as structured representation of implemented issues.
JabRef uses OpenFastTrace to identify each requirement and to link implementation, tests, and more to it. This enables forward and backward tracing. For instance, questions like: “How is the requirement implemented?” (forward trace) or “Which requirement lead to this implementation?” (backward trace).
Specifying requirements
One writes directly below a Markdown heading a requirement identifier.
Example:
### Example
` req~ai.example~1`
It is important that there is no empty line directly after the heading.
One needs to add <!-- markdownlint-disable-file MD022 --> to the end of the file, because the ID of the requirement needs to follow the heading directly.
The space has to be absent in real use. Above, the space is put to have traceRequirements not treating this example as real requirement.
After putting a heading and an identifier, one writes down at the requirement. Directly at the end, one writes that it requires an implementation:
Needs: impl
One can also state that there should be detailed design document (dsn). However, typically in JabRef, we go from the requirement directly to the implementation.
Linking implementations
After writing the requirement, at the implementation, a comment is added that this implementation is covered:
// [impl->req~ai.example~1]
Automated checks
When executing the gradle task traceRequirements, build/tracing.txt is generated. It captures the links between the artifacts (requirement, implementation, …)
In case of a tracing error, one can inspect build/tracing.txt to see which requirements were not covered.
More Information
- General reading on traceability
- User manual of OpenFastTrace
- We cannot copy and paste real examples here, because of openfasttrace#280.