Improve changelog entry separators

[jwodder]

We just started using scriv in a project with a pre-existing CHANGELOG file, and the first scriv-powered release made the top of the CHANGELOG look like this:

<a id='changelog-0.17.6'></a>
# 0.17.6 (2022-09-21)

[lines snipped]

## Tests

- Allow for any 2 from first 3 to be consumed in test_gracefull_death.  [PR
  #7041](https://github.com/datalad/datalad/pull/7041) (by
  [@yarikoptic](https://github.com/yarikoptic))
# 0.17.5 (Fri Sep 02 2022)

Observe that there is no blank line before the pre-existing 0.17.5 entry; is scriv assuming that a nonempty CHANGELOG always starts with a blank line, i.e., that the topmost entry was also generated by scriv?

In addition, we would like to be able to set the changelog entry separator in our changelog to "\n---\n"; could a method for configuring this be added?

[nedbat]

There's no assumption about blank lines, but there is a template for new entries [UPDATE: I meant fragments]. Would it work for you to adjust the template and write it into changelog.d/new_fragment.md.j2?

<!--
A new scriv changelog fragment.

Uncomment the section that is right (remove the HTML comment wrapper).
-->

{% for cat in config.categories -%}
<!--
### {{ cat }}

- A bullet item for the {{ cat }} category.

-->
{% endfor -%}

[jwodder]

I think there may be too much ambiguity with the term "entry." When I used it in the OP (motivated by the fact that the documentation says scriv collect aggregates fragments into "a new entry"), I meant a "CHANGELOG section", i.e., all of the text related to a single release. Your response seems to be using "entry" to mean a "CHANGELOG item" (i.e., something like a single "Fixed a bug" bulleted item). As far as I can tell from scriv's documentation, the new fragment template is only for CHANGELOG items/fragments created with scriv create and has no bearing on the format of CHANGELOG sections created by scriv collect, which is what I'm actually concerned with.

[yarikoptic]

indeed there seems to be confusion between entry and fragment. I think it is "entry" what @jwodder talks about and for which there is entry_title_template but there is no new_entry_template to point to some jinja template which would contain the loop across categories and then instruct how to place fragments or smth like that, and then add possibly that final --- divider.

May be in our case @jwodder you could add spare new line and divider into entry_title_template?

[nedbat]

Sorry, I see what you mean now. And yes, I misspoke in my early comment. There is a template for fragments. I suppose we could add a new_entry_template that would handle the layout of the entire entry as well.

[yarikoptic]

@jwodder is this issue still pertinent for us in datalad/release-action?

[jwodder]

@yarikoptic That's up to you. You're the one who wanted it.

[yarikoptic]

looking into it -- it seems the issue was "addressed" for us since now we do have those blank lines in https://raw.githubusercontent.com/datalad/datalad/f0b4dcb2b99a99941899c2392b43244175d89513/CHANGELOG.md but it is because of the empty line on top of the file, as also was in the original description. So the issue remains somewhat relevant to any case where the prior version of CHANGELOG.md would not have some leading empty new line to provide such separation. Overall it seems to be some "hidden convention of scriv", which would not be an issue for someone who used scriv since initial point of CHANGELOG.md and who doesn't mind those empty lines on top of the file. I will leave it to @nedbat to either do anything about that or no, but I guess we would just need to keep this aspect in mind.