Update release notes for the Markdown era

[colleenmcginnis]

🧀 Pairs with elastic/elastic-agent#9440

Overview

Adds the ability to generate Markdown files for release notes, breaking changes, and deprecations in the new format used on https://www.elastic.co/docs/release-notes/fleet.

Approach

Updates the render command to accept --file_type set to either asciidoc or markdown.

• When set to asciidoc, it renders a single AsciiDoc file containing release notes for a given version using the existing asciidoc-embedded template.
• When set to markdown, it renders three Markdown files for a given version:
  • Release notes use the markdown-index-template template and the resulting file is <version>/index.md.
  • Breaking changes use the markdown-breaking-template template and the resulting file is <version>/breaking.md.
  • Deprecations use the markdown-deprecations-template template and the resulting file is <version>/deprecations.md.

Adds two new fields to the fragment template to be used when the kind is breaking-change, deprecation, or known-issue:

• impact: User impact of the change (a few sentences).
• action: Steps for mitigating the described user impact (a few sentences).

Updates the recommended configuration file name (from config to config.changelog.yaml) and format for individual repos (elastic-agent and fleet-server) in order to save the rendered files in the appropriate location so all versions can be compiled onto a page for each: release notes, breaking changes, and deprecations. See an example of this structure in elastic/elastic-agent#9440.

Open questions

• Can we make impact and action required for breaking-change, deprecation, or known-issue fragments?
• Should we continue to accept template instead of file_type?

[ebeahan]

I'm not very familiar with the codebase, so my comments are fairly high-level.

Can we make impact and action required for breaking-change, deprecation, or known-issue fragments?

I understand breaking-change and deprecation usage.

Can you provide an example of known-issue? I'm probably just missing some context of how to use.

I'm not very familiar with where the best to spot to "enforce" this change. I think if we wanted to require impact and action, it would be in build (this is how we validate in PR checks).

Should we continue to accept template instead of file_type?

I don't have context about the usage of --template to answer. In my limited experience, I've never used that flag.

[elasticmachine]

💚 Build Succeeded

• Buildkite Build
• Commit: c6f48d1

History

• 💚 Build #98 succeeded 07328c8
• 💚 Build #97 succeeded 743b265
• 💔 Build #96 failed 0a22b3d
• 💔 Build #95 failed b6b455c
• 💔 Build #94 failed 3286c50
• 💔 Build #93 failed 450e447

cc @colleenmcginnis

[colleenmcginnis]

Thanks @ebeahan!

I'm not very familiar with the codebase, so my comments are fairly high-level.

Is there anyone else who should review?

Can you provide an example of known-issue? I'm probably just missing some context of how to use.

I initially included automation for adding content to the Markdown known issues page, but I ended up removing it since recently we've been adding known issues manually post-release (example, example, example, example). I'm not sure if we should try to automate those.

I don't have context about the usage of --template to answer. In my limited experience, I've never used that flag.

Prior to this PR, there was only one template available, asciidoc-embedded, which was the default value so there was no reason to use it in the past.

[ebeahan]

Is there anyone else who should review?

Let me reach out to my team and ask for some additional feedback.

[pierrehilbert]

Even if you are no more handling this project, maybe you can still take a look here @endorama?

[pierrehilbert]

From what I know, we are not automatically checking the fragment content but only if a fragment is available in the PR.
Updating the template as you did and communicating that change to the team is probably the best path for now.

[ebeahan]

LGTM.

@colleenmcginnis do create a new release once these changes are merged.