Top-level unordered lists are flattened and appear as separate changes

[EliahKagan]

It looks like when a conventional commit has a top-level unordered list in its commit message, the bullet points are themselves shown in csr-generated changelogs as though they are separate changes of the same kind.

That's what I think is going on in the gix-path v0.10.11 release notes.

If that was not generated in the usual way using cargo-smart-release or some other factor has resulted in the flattening, then this issue may need to be refined or closed, but I figured opening this may be a reasonable first step in investigating it.

---

The following is a simplified but still non-trivial example that illustrates how the effect is misleading. But I am not confident that I have all the details of this bug right; I have not run code from cargo-smart-release to produce this. Instead, it is an illustration of what I mean when I say top-level unordered lists are flattened, and also a demonstration of how in extreme cases it could result in obscuring the distinction between claims intended to be affirmed in release notes and those intended to be denied in release notes.

Suppose I have two conventional commits. This is the first:

fix: Remove hidden bogosort functionality

If users turn out to be depending on bogosort, we may:

- Add instructions for using an earlier version.
- Add back bogosort and document it properly.

We defaulted to bogosort on Tuesdays based on these mistaken beliefs:

- Bogosort runs in O(n log n log log n log log log n) if you have an odd number of RAM sticks.
- The software can never be run on Tuesday.

This is the second:

fix: Time zones are remembered across sessions

I think this will be rendered as something like:

Bug Fixes

• Remove hidden bogosort functionality

  If users turn out to be depending on bogosort, we may:

• Add instructions for using an earlier version.

• Add back bogosort and document it properly.

  We defaulted to bogosort on Tuesdays based on these mistaken beliefs:

• Bogosort runs in O(n log n log log n log log log n) if you have an odd number of RAM sticks.

• The software can never be run on Tuesday.

• Time zones are remembered across sessions

[Byron]

Thanks for reporting - there are probably a lot of bugs related to it not being able to properly show commit messages in bullet-points.

Further, after generating the changelog, when publishing it would not be able to parse these messages back and create a <csr-unknown>the content that it couldn't parse</csr-unknown> tag, effectively removing the content of the message of an entire commit - this is by design and a fallback, but it's definitely not nice.

Probably it would be possible to post-process the message better and make it compatible to be shown in bullet-points.

[EliahKagan]

Is this issue still present? If so, is it more subtle than I had thought? The gix-testtools v0.16.0 release notes show messages from commits with bullet points, and flattening does not occur.

[Byron]

I noticed the same and was quite surprised that it was able to achieve such a feat. Maybe it wasn't the markdown that was broken, but the rendering on GitHub?

[EliahKagan]

Based on the Markdown of the release notes for gix-path 0.10.11 (the example I reported above), it looks to me like the Markdown is at least part of the problem: bullet points that should not be top-level are top-level there.