Make `scriv create` prompt for the category

[agateau-gg]

Instead of generating a fragment with many commented entries, it would be nice if scriv create would prompt the user for the fragment category and create a fragment with only the relevant content.

Doing it this way would make the tool easier to use: no need to comment-out sections, just write the fragment text. It also would make it less error prone: we recently merged a PR where the changelog fragment was filled, but the author forgot to remove the comments.

I put together a proof-of-concept if you want to get a feel of how it could behave. You can find it in this gist. Here are some screenshots of it:

I'd be happy to look into adding this to scriv itself if you think this is a good idea.

[kevinmatthes]

Hi, @agateau-gg,

As another Scriv user, I would like to give you some feedback for your idea.

I agree with you that the selection of a particular category is very useful if Scriv is invoked by a human user. I would like to suggest to make this prompt and / or the current behaviour of scriv create triggered by an option to Scriv as there are certain automations which rely on Scriv being a non-interactive CLI, like the Scriv fragment creation Action which is designed to run headless. Hence, for the concrete implementation, it would be good if the non-interactive mode could be kept somehow to not break something.

Does your prototype allow for the selection of multiple categories? It would be great to be able to select more than one! I experienced multiple cases in which just one category did not suffice as an introduced feature has fixed a known bug, for example. Although there are Scriv fragment policies which enforce the decision for exactly one section of the generated fragment, a more detailed description of what happened should be supported, anyway, because the completeness of the resulting CHANGELOG would benefit from it.

What do you think about these two points, @agateau-gg?

[agateau-gg]

Hence, for the concrete implementation, it would be good if the non-interactive mode could be kept somehow to not break something.

I would expect the non-interactive mode can be kept.

Does your prototype allow for the selection of multiple categories? It would be great to be able to select more than one! I experienced multiple cases in which just one category did not suffice as an introduced feature has fixed a known bug, for example.

Multi-selection can probably be done, but it would be better to use a real TUI library like Textual to do so than my input-based implementation. Having said so, it's possible to add more than one change by either:

• Adding the new change entries manually in the fragment file (maybe the category list could be added as a comment at the end, but that would clutter the fragment file a bit)
• Creating one fragment per change

[kevinmatthes]

Thank you for answer!

During the last days, I have been working on a workaround for the fragment creation Action such that its users can become independent of the actual behaviour of scriv create. Due to this workaround, the Action will become deprecated and will be removed in the long term, so it is no problem regarding that particular automation if the non-interactive mode should need to be dropped for some reason.

For the second point, I agree with you that your suggestions are the best solution options for the selection of multiple categories. These options perfectly answer my question.

So, from my point of view, the new interactive mode can come! 👍

[agateau-gg]

So, from my point of view, the new interactive mode can come! +1

Note that I am not a scriv developer, just a happy user 😅, so no idea if this idea is going to be accepted.

[nedbat]

I like this idea, because I am not enjoying editing out commented sections in the template. To accommodate different workflows, I think I would add an option to scriv create: --category=<words> to specify the category(s) you want to use:

scriv create --category=Fixed

or:

scriv create --category=Fixed,Security

The categories setting would be set to the list provided, so the template would be generated with only those categories. (I guess this still means they are commented out, hmmm: ideas?)

Interactive use is a bit far afield for me, but perhaps --category=: could mean to prompt?

[kevinmatthes]

In order to address the categories being commented out and empty by default, one option might be to harvest a given amount of commits beginning with HEAD in order to extract the fragment entries from the commits' messages.

Many projects have certain commit message policies and usually, one particular category is assigned to the commit. The commit summary thus can be assumed to have the following structure: <category> <delimiter> <change>. This pattern can be employed to create a CHANGELOG fragment from the last $n$ commits such that the commit message summary is split at the first occurrence of the given delimiter into a category and a change. Regarding the implementation, Python's dictionaries might be useful as for each category, there is going to be a list of changes for that category; at the end, the dictionary is converted into the desired output format which will form the automatically generated and filled fragment for further manual editing, at option.

What do you think about this idea?

[nedbat]

Using commit messages (or other sources) as a starting point for the content of a fragment is the subject of issue #13.

[agateau-gg]

The categories setting would be set to the list provided, so the template would be generated with only those categories. (I guess this still means they are commented out, hmmm: ideas?)

I think if the categories have been explicitly provided then they should not be commented out. After all, the user asked for them :)

Interactive use is a bit far afield for me, but perhaps --category=: could mean to prompt?

That would be fine, but I think it would be nicer to have a -i, --interactive option instead, similar to what git rebase does.

[ncoghlan]

One simplification I made to my templates is to make it so there is just one comment block that I can delete with a single d17d in vim: https://github.com/lmstudio-ai/venvstacks/blob/main/changelog.d/new_fragment.rst.j2

It does mean I have to type the category name in directly though, increasing the risk of running into #111