Beats: [Proposal] New Changelog Format

[andresrc]

We would like to evolve to a new changelog management mechanism for this repository. The goals are to:

• Eliminate the coupling between changelog edition and commit history. Besides, changelog entries should not be a “resource under contention” to merge PRs, nor a source of merge conflicts.
• Simplify the review of the changelog entries, increasing the involvement of the engineers introducing the changes in the platform.

In the proposed approach the source of truth for changelog entries will be the original PRs used to introduce the change in the platform. The same entry will be used for all eventual backports.

The changelog entry will be in a section of the description of the PR. Engineers will be responsible for completing this section with an appropriate description and language for the target audience. Tech writers will provide guidelines on how to write good entries and provide reviews/edits but the goal is that the need for edits by the Tech Writers decrease over time as the engineers get used to providing better descriptions. The PR template will be updated to account for this section.

The proposed PR description section for the change log is as follows (the end of the changelog section is delineated by either the next occurrence of a level 2 header or the end of the text itself)

## Changelog

### User Changelog

### Developer Changelog

### Agent Changelog

• The level 2 (##) Changelog section marks the start of the section.
• There are 3 level 3 subsections, once for each of the “first-class” changelogs.
• The content of each of the subsections is considered to be everything inside it, up to any other section (regardless of level) or the end of the description. Whitespace / blank lines before after the content should be stripped.

Some labels to annotate the entry or alter the processing include:

• The release-note:skip label makes the PR be ignored when processing the PRs.
• The release-note:highlight label marks the content to be included as a release highlight.
• The release-note:breaking label marks the content as a breaking change.
• The release-note:deprecation label marks the content to be included in the deprecation section.
• The release-note:fix label marks the content to be included as a fix.
• If none of the previous labels is added the content is included in the “Added” section.

In the user changelog, content should be organized in paragraphs, each one starting with the text [All], [Filebeat], [Metricbeat], etc. This allows a single PR to provide multiple entries for multiple products.

[elasticmachine]

Pinging @elastic/integrations (Team:Integrations)

[elasticmachine]

Pinging @elastic/ingest-management (Team:Ingest Management)

[elasticmachine]

Pinging @elastic/siem (Team:SIEM)

[ycombinator]

Will there be some protection to block the PR from being merged if there is no CHANGELOG content and release-note:skip is not set? IIRC the Kibana team has something like this for their PRs.

[ycombinator]

Just curious why Agent Changelog needs a separate section as opposed to using [Agent] like for other products?

[andresrc]

Agent documentation may have (now or in the future) a different structure than the current beats, so we are providing separate treatment from the beginning.

Yes, we will need to add some protections.

[ph]

@ycombinator we also plan at some point to move out of the beats repository.