Uid name

[sebhub]

Make the item UID a bit more flexible so that it can contain a number or a name part. This enables user-specified names for items, e.g. REQ-ABC.yml. The new command line option can be also used to specify a user provided number, e.g. doorstop add -n 99 REQ creates REQ-099.yml.

[sebhub]

I think the code coverage threshold should be a bit tweaked. The change by -0.02% was probably a false positive code coverage degeneration.

[jacebrowning]

@sebhub Can you provide an example of how you intend to use this feature?

REQ-ABC does not looks like any requirement ID I've ever seen. 😄

[sebhub]

We would like to use Doorstop not only for requirements, but more general for all sorts of specifications. I started to work on a new build system for RTEMS which uses waf and Doorstop:

https://git.rtems.org/sebh/rtems.git/tree/spec?h=build

An example for an UID would be RTEMS-BUILD-BSP-OPT instead of RTEMS-BUILD-BSP-004 or RTEMS-BUILD-BSP-OPTSIZE instead of RTEMS-BUILD-BSP-005. The build specification can be also used for the configuration of static analysis tools, documentation generation (Doxygen), a Software Configuration File, etc.

[JustinW80]

While I accept the view that the app should be flexible to users' preferred use cases, I still question that putting semantic meeting into a requirement's (or any item's) UID should be encouraged.

UIDs are a permalink. What happens if the requirement's payload changes to no longer match the meaning in the UID? For example, suppose Doorstop had REQ-USE-MD5say to use MD5 for the hash algorithm, but now we want to change to SHA-256.

[sebhub]

The names are optional. You have to use a command line option. By default, numbers are generated as usual. I don't think this encourages the use of names. Whenever you use something optional and walk away from the standard path, it is your responsibility to think twice what you do.

With respect to your example. Is is a good idea to drastically change a requirement and keep the UID? In addtion, requirements should be independent of a particular solution (e.g. MD5 or SHA256).

[JustinW80]

The names are optional. You have to use a command line option. By default, numbers are generated as usual. I don't think this encourages the use of names. Whenever you use something optional and walk away from the standard path, it is your responsibility to think twice what you do.

Yes, making it an optional for power users should hopefully mean they know what they're doing.

With respect to your example. Is is a good idea to drastically change a requirement and keep the UID? In addtion, requirements should be independent of a particular solution (e.g. MD5 or SHA256).

My idea is that all the places that link to REQ-USE-MD5 can trace the change to SHA256 if you keep the same requirements with a change rather than delete REQ-USE-MD5 and add REQ-USE-SHA256. I agree that if you were to name this requirement, REQ-HASH-FCN would probably be better, but I guess my worry is that a novice user could end up hurting themselves with more work with a poorly chosen name.

Maybe we could have a command to rename an item's UID?

doorstop rename REQ-USE-MD5 REQ-USE-SHA256

This could be useful even if you don't use --name to set a custom ID. Maybe even doorstop mv if you can move an item to another document?

doorstop mv REQ-USE-MD5 REQ-HASH-FCN # renames item in REQ
doorstop mv REQ-HASH-FCN LLR         # moves the item to document LLR
doorstop mv REQ-001 LLR --name OPT   # moves item to LLR with a custom name. Result is LLR-OPT

[sebhub]

A command to move an item sounds useful. What should it do?

1. Create the target item.

2. Mark the source item as inactive (active = false).

3. Change all links from source to target.

[sebhub]

In case there are no general objections, it would be nice if someone can review this patch set if it is technically all right. I would like to start further work once it is integrated.

[sebhub]

I started to use this feature for my work on a build system specification. I think that UIDs with names are much more easy to use than UIDs with plain numbers. I will have to add about 1000 items for the build specification and another 1000 to 10000 items for the basic RTEMS specification. Here is an example document with names:

https://git.rtems.org/sebh/rtems.git/tree/spec/build/testsuites/samples?h=build

The items are used by a waf based build script:

https://git.rtems.org/sebh/rtems.git/tree/wscript?h=build

[JustinW80]

Could you add the new --separator, --name, and --number options as an examples in doorstop/docs/cli/creation.md?

[sebhub]

The continuous-integration/travis-ci/pr failure seems to be unrelated to my recent commit.