Item templates

[NouberNou]

Intent is to allow for adding new items to pull templated text into the item from template files stored in the root of the project within a directory called .doorstop.

This includes a default template and a new --template parameter to doorstop add.

Rationale: Too lazy to constantly copy and paste in the default template for requirement structure that my organization is using for every requirement (like subheaders for rationale, other requirement information).

Looking for recommendations on how templates should be added, the .doorstop directory is just something I came up with on the fly, and seemed reasonable.

[NouberNou]

I am not sure what the diff failures mean in the CI tests?

[michaelnt]

The make check failed.

You need to run that command, which will run the black formatter and a command to sort the imports. Then check in those format changes.

[NouberNou]

Thanks!

Of course now that kicked test_document.py over the pylint line limit, haha!

[NouberNou]

I understand module size limits in functional code, but it seems a bit overkill in test files.

[NouberNou]

Updated pylint ignores for that test based on the precedence of it being done in the items test suite.

[sebhub]

This looks like a duplication of the custom default values for attributes that was added recently, see #70 and #330.

Related is a feature proposal #367.

[NouberNou]

While I agree that this is a similar system at first glance, I believe that proposing something wholly owned by doorstop is the most prudent in this situation.

Do not dismiss my gratitude for such an edenvenour though as my next conquest was that of the markdown system and how YAML and MD could support a more dynamic and supportive ecosystem.

[RomainTT]

Hi,
could you write some documentation about your feature please ? You want to highlight that it is different from the other issues mentioned above, so a bit of explanations with examples and so on would be nice.

I think I like your way of thinking with the concept of "template", but for now I find it a bit in conflict with the work of #366.

[NouberNou]

Sure. The documentation is pretty simple:

1. Place a folder in your root project directory named .doorstop. This should be the same folder where you normally run the doorstop command from.
2. Place template files in there, nominally files with the extension .md, for example my-template.md and populate file with your custom default item text content.
3. When adding a new item with doorstop use the following argument --template=my-template.md

This will produce a new item with the next field populated by the contents of my-template.md.

Alternatively, place a file called default.md in the .doorstop folder and this will be used for any new item that does not specify the --template option.

[NouberNou]

The intent is similar, but this is a more dynamic way of doing it. Alternatively moving to something that is more dynamic than just a single .doorstop.yml file would also be appropriate.

The problem I am addressing is that different requirements have different fields by default, and being able to create a test requirement vs. a functional requirement with its default layout has more merit than one single default value.

[NouberNou]

Any more thoughts on this?

[RomainTT]

I don’t know what the others think, but in my opinion there should not be both implementations from 6c91fab and this PR.

I personally prefer the way of this PR concerning the management of defaults values. Therefore, my suggestion is to revert 6c91fab in order to replace it by this new implementation.

Note that the documentation for this PR should be present in docs/reference/items.md, and would replace the one from 6c91fab.

Also note that this replacement would still be compatible with the feature from c8834c8 (reviewed extended attributes).

I don’t know if an actual git revert is enough, as many commits were pushed since.

[sebhub]

The existing support for default attributes is document-specific. I would not remove this feature. I think this commit series should be refactored to better use the infrastructure that is already in place. You can for example apply the command-specific default attributes after the document-specific default attributes with a second call to Item.set_attributes(). For the project-specific default attributes, I would add them to the top level .doorstop.yml or solve it via the include feature #367 in favour of adding a new .doorstop file.

[sebhub]

With the include support you could simply place this into the .doorstop.yml:

settings:
  ...
attributes: !include template.yml

In template.yml:

text: 'Your template text'

[sebhub]

You can find a proof of concept for the include feature here:

sebhub@9048234

[sebhub]

Please check if #403 does what you need.

[NouberNou]

Sorry, was away over the weekend. I'll try to get a look at it today.

[NouberNou]

Yea that looks good, but I'd highly recommend describing in the documentation what a default.yml file should look like. Does it have to be an exact copy of a requirements yml? Can it specify only the fields wanted and it'll just override those?

How does it differ from the defaults in the .doorstop file?

It looks like it is functionally the same, but less clear on its usage, which has a been a problem in general with Doorstop documentation that I am getting reported by a number of people in my organization that are evaluating it right now.

I'll close this PR for now.