Doorstop Issues

[Sebastian Huber]

On 20/04/2020 09:45, Chris Johns wrote:

>> On 20 Apr 2020, at 3:21 pm, Sebastian Huber <sebastian.huber at embedded-brains.de> wrote:
>>
>> On 20/04/2020 07:12, Chris Johns wrote:
>>
>>>> On 20/4/20 1:14 am, 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.
>>> Have you discussed these issues with the Doorstop project?
>> Not yet, but it would be quite a big change in Doorstop to fix these issues.
>>>> With Python, this is quite easy. I already have the infrastructure for this in:
>>>>
>>>> https://git.rtems.org/sebh/rtems-qual.git/
>>> Why not place the tool in the rtems-tools repo? This repo exists for this purpose.
>> Now I am a bit confused. You wanted to have all the pre-qualification stuff separated.
> I maybe confused about the tool and it’s role.
>
> Is the new build system based on YAML files this tool will manage? Before this change it was Doorstop which we installed as an external package.

The wscript of the new build system never depended on Doorstop. It 
simply loads the YAML files and works with them as is. Managing the 
files (e.g. adding new files, linking files) was done partly by 
Doorstop, but this can be done easily with a text editor alone. I can 
add a "./waf verify-spec" command to check that the build specification 
items are all right.

The build specification is only a subset of the specification. 
Everything else of the specification is contained in this separate 
rtems-qual.git repository. Here I would like to add the tools for the 
pre-qualification project.