[Maintainer doc] Detail expected format of CHANGELOG.md

[wiibaa]

Starting from #5081 reporting CHANGELOG rendering issue on github and after reviewing several CHANGELOG.md in different plugins, I thought that there is room for improvement in harmonizing how the changelog is actually formatted.

• This PR contains documentation proposal, preview available here
• Review CHANGELOG format logstash-plugins/logstash-filter-date#64 apply the defined rules to the date filter plugin, you can compare current to proposed

@ph please review and discuss with the team, I'm waiting for your green light before looking to other plugins changelog ;)

[ghost]

Jenkins standing by to test this. If you aren't a maintainer, you can ignore this comment. Someone with commit access, please review this and clear it for Jenkins to run; then say 'jenkins, test it'.

[ph]

I though # was header level 1 and ## was header level 2?

[wiibaa]

My last read was asciidoctor where they separate document title from section title http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#section-titles

But in markdown I should indeed say header level-2

[ph]

@elastic/logstash Hey guys, what do you think of this?

[suyograo]

@wiibaa Good suggestion, but what about having just 2 tags: internal and docs. I want to make sure creating CHANGELOG is not a lot of overhead. WDYT?

[wiibaa]

@suyograo As discussed with @ph in #5081 an additional goal could be to simplify (or automate) the creation of the main logstash changelog

In recent versions, we can see how it is carefully crafted, so the final presentation of info in this changelog is the driver for the usage of tags upstream. So you decide what you need first, but I see a pattern :). Please see table below

Logstash changelog for humans	tag in plugins changelog
Added... Improved... Better... Support...	improvment
Fixed... Fixed bug... Resolved...	bugfix
Breaking change... Backward incompatible...	config,breaking

IMHO I do not see a big overhead using tags in the changelog, because they should be derived from the labels used for triage on the github issues. The matter here is to define a sane starting point that bring clear added value.

Thinking about the main changelog and giving my 2 cents, I would be tempted to order and group the changes in:

• config change first new / deprecated / breaking
• bugfix and improvment (improvment with config change already covered in 1st section)
• internal

Thoughts ?

[suyograo]

@wiibaa Thanks for your explanation. LGTM

[elasticsearch-bot]

Suyog Rao merged this into the following branches!

Branch	Commits
master	7cd1f89, 4a5216b
5.0	9f42f65, 7123215
2.3	7d28e7a, 2a27e04
2.x	bd7fff8, 1caf49a