CHANGELOG.md inconsistent format => not displaying correctly on github

[wiibaa]

A lot of CHANGELOG.md files do not contains a blank line to separate first level titles, therefore they are not rendered correctly, for example https://github.com/logstash-plugins/logstash-filter-date/blob/master/CHANGELOG.md jumps from 2.0 to 2.1.6

Also from https://raw.githubusercontent.com/logstash-plugins/logstash-input-jdbc/master/CHANGELOG.md second level heading are used

@suyograo can the detailed markdown format of changelog be strengthened and clearly specified in https://www.elastic.co/guide/en/logstash/current/_versioning_plugins.html. It could improve readability a lot when reading it in different plugins, or they could even be injected in ELK to display evolution of the Logstash plugin ecosystem or power a crazy logstash-caniuse (as http://caniuse.com) if someone has some free-time

@ph can a bulk magic be applied here to correct / validate these files with advanced regex/grokking and maybe integrated in the CI ?

I may be reading changelog too much lately... :D

[ph]

@wiibaa Don't stop reading them!

It might be possible to create a script to clean them up

• lookup for # + the version scheme and add new line?
• Then we can clean them to make sure the headers uses the first level title.

For the CI you mean, correcting the format on push? Or making sure we have one?
I think the format validation should be part of the review process.

Concerning: https://www.elastic.co/guide/en/logstash/current/_versioning_plugins.html Would you mind doing a PR for that? I agree we need to use the same structure everywhere.

[wiibaa]

@ph I made a first try in the filter-date plugin, please have a look.

First I strongly suspect that the missing newline was introduced by the mass update, and followed by human-error copy-pasting, can you add a newline in the mass update when writing the changelog already please.

When possible, I will prepare a PR to the doc, my idea is to propose some general rules first:

• version should be a second-level header
• each change should be started with - (one space one dash one space)
• optional usage of comma-separated tags ended by a colon
• multi-line description must be aligned under first line (3 spaces indent)
• newline after version block

Translated in regex to validated the file, and tested against my proposal for date filter it becomes
(not incuding a specific match for tags yet)
/\A(?:^## \d\.\d\.\d(?: \(yanked\))?$(?:\n^ - .*$(?:\n^ .*$)*)+\n+)+\z/

Question: Do you know if the changelog is used outside of github in the documentation or elsewhere, it would have an impact on how links to issues should be written.

[ph]

First I strongly suspect that the missing newline was introduced by the mass update, and followed by human-error copy-pasting, can you add a newline in the mass update when writing the changelog already please.

Yeah I believe the same 🐼

• version should be a second-level header
  +1
• each change should be started with - (one space one dash one space)
  +1
• optional usage of comma-separated tags ended by a colon

Not sure what you mean here? Any example?

• multi-line description must be aligned under first line (3 spaces indent)
• 1, I am more in favor of using word wrap here for simplicity.
• newline after version block
  +1

Question: Do you know if the changelog is used outside of github in the documentation or elsewhere, it would have an impact on how links to issues should be written.

To my knowledge I do not think this is used elsewhere, I think for simplicity we can stay with only using the number.

I can see in a future a tool that goes through all the plugins for a specific logstash build and create the plugin changelog to be merged with the logstash changelog.

[wiibaa]

To my knowledge I do not think this is used elsewhere, I think for simplicity we can stay with only using the number.

The point is that each changelog can be different, I found out

• Simple URL Ref: https://github.com/elastic/logstash/pull/3895
• Github short link #65
• Markdown links [#81](https://github.com/logstash-plugins/logstash-input-file/issues/89)

either at the beginning or the end of the change entry.

Any recommendation here to go further ?

[ph]

OK, lets take the latest entries from the 2.3 changelog as the starting point of this.

Full link to the issue using markdown links [#81](https://github.com/logstash-plugins/logstash-input-file/issues/89), This make it easy to create post or aggregate changelog by a script if needed.

Reference at the end of summary of the change.

Preferably at the end of the summary, but I don't think we really need to enforce that. Summaries can point to multiples issues or PRs.