Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Maintainer doc] Detail expected format of CHANGELOG.md #5103

Closed
wants to merge 2 commits into from
Closed

[Maintainer doc] Detail expected format of CHANGELOG.md #5103

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c34ff16
describe CHANGELOG.md expected format
wiibaa Apr 12, 2016
5157ae5
correct explanation about header level
wiibaa Apr 13, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 34 additions & 4 deletions docs/static/maintainer-guide.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -88,10 +88,40 @@ should kept to the minimum.

Every plugin should have a changelog (CHANGELOG.md). If not, please create one. When changes are made to a plugin, make sure to include a changelog entry under the respective version to document the change. The changelog should be easily understood from a user point of view. As we iterate and release plugins rapidly, users use the changelog as a mechanism for deciding whether to update.

Changes that are not user facing should be tagged as “Internal: ”. For example:

* "Internal: Refactored specs for better testing"
* "Default timeout configuration changed from 10s to 5s"
Changes that are not user facing should be tagged as `internal:`. For example:

[source,markdown]
- internal: Refactored specs for better testing
- config: Default timeout configuration changed from 10s to 5s

===== Detailed format of CHANGELOG.md

Sharing a similar format of CHANGELOG.md in plugins ease readability for users.
Please see following annotated example and see a concrete example in https://raw.githubusercontent.com/logstash-plugins/logstash-filter-date/master/CHANGELOG.md[logstash-filter-date].

[source,markdown]
----
## 1.0.x // <1> <2>
- change description // <3>
- tag: change description // <3> <4>
- tag1,tag2: change description // <3> <5>
- tag: Multi-line description // <3> <6>
must be indented and can use
additional markdown syntax
// <7>
## 1.0.0 // <8>
[...]

----
<1> Latest version is the first line of CHANGELOG.md
<2> Each version identifier should be a level-1 section title using `##`
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

<3> One change description is described as a list item using a dash `-` aligned under the version identifier
<4> One change can be tagged by a word and suffixed by `:`. +
Common tags are `bugfix`, `feature`, `doc`, `test` or `internal`.
<5> One change can have multiple tags separated by a comma and suffixed by `:`
<6> A multi-line change description must be properly indented
<7> Please take care to *separate versions with an empty line*
<8> Previous version identifier

==== Continuous Integration

Expand Down