MPS 2020.2 Help

Requirement tracking language

This cookbook will guide you through the Requirement tracking sample project.  This sample projects implements language-agnostic requirement tracking. Along the way it illustrates several useful language constructs:

  • Node attributes to annotate nodes of different languages

  • Multiple editors (presentations) per concept and switching between them with editor hints

  • Programmatic access to the selected editor hints as well as programmatic selection of an editor

  • Reference scoping to avoid repetition in collections of references

The Requirement tracking sample project comes bundled with MPS, so you'll find it among the other sample projects in your home directory.

mps welcome png

 

Purpose

Most of software as well as other project start with requirement gathering. During this phase the client specifies the desired functionality of the system that should be built. The specification is then used by the developers to lead their decisions during the implementation phase. Typically the specification is written in some form of textual documents, while software is delivered as code. This approach suffers from several limitations:

  • Tracking which piece of code implements which requirements becomes tedious manual work with high probability of errors.

  • Answering questions like "Which requirement mandates a particular piece of code" or "Where in code is a particular requirement implemented" is not instant and automated.

  • Analysis of impact of individual requirements on software modules is not trivial.

  • When a requirement changes, listing all impacted pieces of code is not reliable.

The Requirement Tracking sample illustrates a possible automated solution to requirement tracking, which handles all the listed deficiencies of manual tracking.

image2018 9 12 11 23 3 png

Code, be it XML, Java or any other MPS language, is annotated with requirement traces - brief summaries of the requirements implemented by that particular piece of code. The requirement traces can be attached to nodes on any granularity level - to a class, method or a statement, for example.

image2018 9 12 11 24 43 png

The requirement traces can be added, edited and removed at will.

image2018 9 12 11 31 47 png

Intentions are utilised to add/remove requirement traces to nodes.

image2018 9 12 11 42 16 png

Since the requirements have not been written in some text editor external to MPS, but in MPS using a language designed specifically for writing requirements, the standard Go To Declaration Ctrl+Space action will open the referenced requirement in the editor and the user can quickly navigate to the full description of the requirement.

image2018 9 12 11 32 57 png

Show Usages Alt+F7 for a particular requirement will bring up a list of all places in code, from where the requirement is referred to with a requirement trace:

image2018 9 12 11 35 26 png

The requirement traces can be made visible or hidden through the standard MPS mechanism for handling multiple projections/editors - editor hints:

image2018 9 12 11 27 42 png

When the ShowTraces hint is not selected, no requirement traces are shown to the user.

Key highlights

  • Specifications are written in MPS, so that they are well structured and referencable from code. They can be generated into plain text documents. If additional generators are provided, the specification could be generated into PDF or other text formats.

  • Requirement traces refer to the particular entries in the specification, show a summary of the referred requirement entry and allow navigation.

  • Any node in any language can have requirement traces attached - BaseLanguage and XML were two example languages given, but any DSL code could be annotated just as well, e.g. Kaja.

image2018 9 12 11 49 58 png

Project structure

image2018 9 12 11 51 33 png

  • The RequirementDefinitions languages enables users to write their requirements/specifications in MPS. A simple TextGen defined in that language generates plain text files containing the requirements.

  • The Specification solution is an example of requirements specification. The requirements are organized into models by their respective concerned sub-systems.

  • The ProjectCode solution simulates the actual code of a project that must conform to the specification contained in the Specification solution. The code is organized by functionality into models. Each model imports the relevant specification models from the Specification solution. The code, both Java and XML is annotated with requirement traces. The traces are only visible, when the ShowTraces editor hint is pushed. With intentions additional traces can be added or removed.

  • The Traces languages defines an attribute that can be attached to any node (BaseConcept). The attribute holds references to the requirement entries in the requirement specifications. Two editors are available - a default one, which only shows the original code, and a "ShowTraces" one, which displays the requirement traces next to the code. "Push hints" can be used to switch between the two editors. An intention is available to attach/detach the attribute to nodes. When the RequirementTrace attribute is being added through the intention to a node, the "ShowTraces" editor hint is selected programmatically, so that the user can instantly see the requirement traces in the code. Multiple traces can be specified for an attribute. Scoping for RequirementEntryReference ensures that the user cannot enter a specific trace multiple times for the same attribute.

RequirementDefinitions language

This language must be imported by solutions that should contain requirement specifications. The language introduces two concepts with editors and textgen.

image2018 9 13 13 17 40 png

The Entry concept uses the jetbrains.mps.lang.text language to allow free text editing in the description part. Custom presentation is defined for Entry to accommodate for the optional reference id value, which may be absent.

Specification solution

image2018 9 12 12 8 47 png

This solution uses the RequirementDefinition language to define requirements for a hypothetical system. The requirements are split into two models:

  • coreRequirements - to specify the business logic of the future system

  • uiRequirements - to specify the user interface of the application

Within each model multiple specification documents can be created.

image2018 9 12 12 11 45 png

Each document contains a collection of requirement entries, each of which has a name, description and an optional reference id.

image2018 9 12 12 13 31 png

The specification models have to import at least two languages - jetbrains.mps.samples.requirementTracking.RequirementDefinition and jetbrains.mps.lang.text.

image2018 9 12 12 18 35 png

ProjectCode solution

The ProjectCode solution contains the actual implementation of the system. The project consists of three models, each of them hypothetically implements a different part of the system.

image2018 9 12 12 24 52 png

On top of the languages used for development the models must import the Traces language in order to define requirement traces.

image2018 9 12 12 26 43 png

The Dependencies of the models must hold the models of the Specification solution, the requirements of which are relevant for code in the model. The persistence model, for example, depends on coreRequirements.

image2018 9 12 12 29 44 png

The ui model depends on uiRequirements.

image2018 9 12 12 30 54 png

This allows requirement traces to be inserted into code. An intention is available to add/remove traces to a node.

image2018 9 12 12 33 32 png

The traces can then be edited directly.

image2018 9 12 12 34 18 png

Traces language

The Traces language glues together the specifications and code. It contains two concepts:

  • RequirementEntryReference - a smart reference to a single requirement document entry

  • RequirementTrace - a node attribute that can be attached to any node (BaseConcept) and holds a collection of RequirementEntryReferences.

image2018 9 12 12 14 24 png

The header of the RequirementTrace concept defines:

  • multiple: false - cardinality of the attribute is 0..1 (at most one can be attached to a node)

  • role: requirement trace - to access the attribute from code, "node.@requirement trace" will be used

  • attributed concept: BaseConcept - it can be applied to BaseConcept

image2018 9 12 12 40 37 png

RequirementTrace provides two editors:

  • The default editor only shows the attributed node, which makes the requirement traces invisible

  • The ShowTraces editor shows the traces next to the attributed node

The ToggleRequirementTrace intention not only adds/removes traces, but also activates the ShowTraces editor hint, when a trace is added, so that the traces become visible, if they were not prior to invoking the intention. This is a natural usability feature.

The RequirementEntryReference editor uses the customized presentation of Entry to optionally show the reference id. RequirementEntryReference implements scoping in a way that filters out the requirements already referred to from the same requirement trace.

image2018 9 13 13 16 55 png

 

 

 

Last modified: 14 August 2020
Description commentsCommenting out nodes