Skip to content

Dotstop

Dotstop is an in-development text-based requirements management package. It is similar to doorstop, but uses a decoupled representation of the edges and nodes of the requirements graph both in memory and on disk. This has significant advantages for modularity and scalability, particularly for large software projects distributed across multiple repositories or even multiple platforms.

Concept1

In the simplest sense, dotstop is just a set of uniquely named markdown files that are linked by edges described in a .dot or "DAG of tomorrow" file.

.dot is a near-universal and open-source language for describing directed acyclic graphs. This has many benefits for data analysis of Trustable, since .dot can be directly parsed by many powerful open-source network analysis and visualization tools, such as:

dotstop uses two small (and syntax-compliant) extensions to the .dot language. First, dot's custom node and edge attributes are used to store the hashes of items and their links:

"ITEM-001" [sha="<hash of file content>"]
"ITEM-001" --> "ITEM-002" [sha = "<hash of concatenated file contents>"]

This allows the Suspect status of items and links to be straightforwardly and robustly tracked.

Secondly, .dot supports C++ style comments (/*,*/ and //) and ignores all lines beginning with #. Crucially though, such lines are not considered comments. Since links (and their hashes) are stored separately from the content of items, handling external dependencies can be reduced to a simple namespacing problem:

# import https://github.com/project/project.git@sha as project
"project.ITEM-001" [sha="<hash of file content>"]
"project.ITEM-001" --> "ITEM-002" [sha = "<hash of concatenated file contents>"]

Implementation

Warning

Dotstop has now been developed to the point where we have fully deprecated doorstop as a viable backend.

The first important type introduced by dotstop is the Item class. These objects possess all the data and functionality associated with a set of Statements:

  • Statement names (hashed)
  • Statement text (hashed)
  • Artifact references (hashed)
  • Status (normative/non-normative) (hashed)
  • Expression as a header
  • Parent document
  • Score
  • Ordering, level-based and/or alphabetical

The second crucial type is the Graph class. Using a pydot.Graph representation of the .dot file, this object provides all of the data and functionality associated with the relationship between the set of Statements and the wider project:

  • Network adjacency matrix
  • Representation as .dot source
  • Review status of Items, based on item hashes
  • Link status, based on item hashes

Roadmap

Dotstop is under heavy development, and the design sketch below is for context only:

flowchart TB;
    subgraph trustablemodule["`**trudag**`"]
        direction BT
        cli["`**trudag.cli**`"]
        score["`**trudag.score**`"]
        manage["`**trudag.manage**`"]
        plot["`**trudag.plot**`"]
        subgraph publishmodule["`**trudag.publish**`"]
            direction BT
            Report["`_trudag.publish.Report_`"]
        end
        plot
        manage --"called by"-->cli
        plot --"called by"--> cli
        publishmodule --"called by"--> cli
        score --"called by"--> cli
    end
    graphalyzer --"called by"--> score;
    score --"called by"--> Report
    subgraph graphalyzer["`**graphalyzer**`"]
        DirectedAcyclicGraph["`_graphalyzer.DirectedAcyclicGraph_`"]
    end
    DotstopGraph --"built from"--> DirectedAcyclicGraph
    DotstopGraph --"member of"--> Report
    dotstopmodule --"called by"--> plot
    dotstopmodule --"called by"--> manage
    subgraph dotstopmodule["`**dotstop**`"];
        DotstopGraph["`_dotstop.Graph_`"]
        PydotGraph["`_pydot.Graph_`"]
        MarkdownItem["`_dotstop.MarkdownItem_`"]
        MarkdownItem --"member of"--> DotstopGraph;
        PydotGraph --"member of"-->DotstopGraph;
    end
    dot --"read/write"--> PydotGraph;
    item --"read/write"--> MarkdownItem;
    subgraph Disk;
        dot[/graph.dot/]
        item[/ITEM-*.md/]
    end

  1. This section is intended to serve as motivation for the goals of the project and the technical decisions being made. These features are not yet implemented. ↩