Changelog can not be linted

[thompson-tomo]

The changelog being generated for https://github.com/open-telemetry/opentelemetry-ruby-contrib fails markdown linting for a range of reasons:

• MD001/heading-increment Heading levels should only increment by one level at a time [Expected: h2; Actual: h3]: There is no h2 heading above the versions hence jumping from h1 page title to h3 version
• MD004/ul-style Unordered list style [Expected: asterisk; Actual: dash]: For pages which have existing changelogs using - this error is thrown. It should be configurable what symbol is used.
• MD009/no-trailing-spaces Trailing spaces [Expected: 0 or 2; Actual: 1]: change log entries should have trailing whitespace removed.

These 3 issues are most of the 481 errors being reported for that one repo.

Other issues observed is that empty lines are sometimes being added between items. This likely ties into MD009 and not trimming. For this there is 230 instances which can be found using the following regex \*.+\R\R\*

[dazuma]

@thompson-tomo Thanks! I'm looking into these now.

[dazuma]

• The heading-increment issue can be addressed via [Toys-release] Provide a way to configure the version header format in the changelog #386.
• For the ul-style issue, I can add a configuration for choosing hyphen vs asterisk. Opened [Toys-release] Add a configuration for choosing to use hyphens vs asterisks in changelog entries #417 to track this feature request.
• For the no-trailing-spaces issue, yes, it would be a good idea to strip the strings when building changelog entries. Opened [Toys-release] Remove trailing whitespace from changelog entries #418 to track this feature request.
• For the empty lines, I'm not sure where that is coming from. It could be due to rogue newlines in the commit messages that should be stripped out by [Toys-release] Remove trailing whitespace from changelog entries #418, or it could also already have been fixed when I redid the implementation last month. I'll keep an eye on it, but please let me know if you see it again for any new releases.

In any case, I'll prioritize the above items (#386, #417, and #418) and get those out shortly. I'll leave this issue open until then for reference. Once that's done, we should be able to have a script do a one-time update of the existing changelogs. Please let me know soon if there are any other common failure patterns I should look into.

[thompson-tomo]

Thanks for the feedback, looking at https://github.com/markdownlint/markdownlint/blob/main/docs/RULES.md the only other one's which I think could be an issue is MD022 & MD032 but on otel contrib I think there was only 1 or instances so think that was already ok.

In relation to fixing the issues I am more than happy to run mdlint to apply the fixes that way you don't need to replicate what is already available in other tools.

[thompson-tomo]

@dazuma i have worked out to reproduce the rogue blank lines. The tool is adding a blank line after the breaking changes have been listed but before any other commits/items are listed.

[dazuma]

@dazuma i have worked out to reproduce the rogue blank lines. The tool is adding a blank line after the breaking changes have been listed but before any other commits/items are listed.

@thompson-tomo Okay that makes sense. I'm pretty sure that behavior went away when I did the large refactor a month or so ago (which is now live on contrib, but still pending on main: open-telemetry/opentelemetry-ruby#2006). I'm pretty sure it won't reappear on any new releases moving forward, but we'll keep an eye on it.

[dazuma]

Current status:

• ul-style can now be configured as of toys-release 0.6.0
• Trailing spaces should be removed as of toys-release 0.6.0
• I'm pretty sure empty lines are not generated by toys-release (but were in the earlier system)
• MD022 and MD032 should already enforced by toys-release (and should have been enforced by the earlier system as well). Any appearance in past changelog entries is probably due to manual edits.

Still to do:

• I still need to implement [Toys-release] Provide a way to configure the version header format in the changelog #386 which should provide a way to address the heading-increment issue. That's next on the agenda.

[thompson-tomo]

Thanks for the update and your support in working through these things.