Doorstop Issues

[Sebastian Huber]

On 19/04/2020 17:14, Sebastian Huber wrote:

> Hello,
>
> I am about to add the next couple of hundred specification items for 
> the RTEMS pre-qualification activity. Before I do this, I would like 
> to present some issues that popped up during my daily work with 
> Doorstop. Doorstop is a requirements management tool which was 
> selected for the pre-qualification activity:
>
> https://docs.rtems.org/branches/master/eng/req-eng.html#selected-tool-doorstop 
>
>
> I am quite happy that Jan Sommer suggested to use this tool. I has 
> some pretty nice features. In particular, I think the file based 
> organization in YAML format forming a directed acyclic graph is really 
> the right thing for this project. However, it turned out that it lacks 
> the required flexibility.
>
> 1. Its use case is requirements management. So it has some standard 
> attributes useful in this domain, like derived, header, level, 
> normative, ref, reviewed, and text. However, I want to use it more 
> generally for specification items and these attributes make not always 
> sense. Having them in every item is just overhead and may cause 
> confusion.
>
> 2. The links cannot have custom attributes, e.g. role, enabled-by.
>
> 3. Inside a document (directory) items are supposed to have a common 
> type. I would like to store at a hierarchy level also distinct 
> specializations.
>
> 4. The verification if the items is quite limited. We need 
> verification with type-based rules.
>
> 5. The UIDs in combination with the document hierarchy lead to 
> duplication, e.g. a/b/c/a-b-c-d.yml. You have the path (a/b/c) also in 
> the file name (a-b-c). You cannot have relative UIDs in links (e.g. 
> ../parent-req) . The specification items may contain multiple 
> requirements, e.g. min/max attributes. There is no way to identify them.
>
> I will probably stop using Doorstop and use a custom tooling. With 
> Python, this is quite easy. I already have the infrastructure for this 
> in:
>
> https://git.rtems.org/sebh/rtems-qual.git/
>
> I will try this out with the new build system.

I forgot another issue:

6. The links are ordered by Doorstop alphabetically by UID. It would be 
better to use the order specified by the user. For example, I had to add 
an "order" attribute for the new build system to work around this feature.