Update release notes for the Markdown era

changelog/fragments/1755717164-markdown.yaml

@@ -0,0 +1,55 @@
+# REQUIRED
+# Kind can be one of:
+# - breaking-change: a change to previously-documented behavior
+# - deprecation: functionality that is being removed in a later release
+# - bug-fix: fixes a problem in a previous version
+# - enhancement: extends functionality but does not break or fix existing behavior
+# - feature: new functionality
+# - known-issue: problems that we are aware of in a given version
+# - security: impacts on the security of a product or a user’s deployment.
+# - upgrade: important information for someone upgrading from a prior version
+# - other: does not fit into any of the other categories
+kind: feature
+
+# REQUIRED for all kinds
+# Change summary; a 80ish characters long description of the change.
+summary: Support outputting Markdown files.
+
+# REQUIRED for breaking-change, deprecation, known-issue
+# Long description; in case the summary is not enough to describe the change
+# this field accommodate a description without length limits.
+description: |
+  Updates the `render` command to accept `--file_type` set to either `asciidoc` or `markdown`.
+
+  When set to `asciidoc`, it renders a single AsciiDoc file 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: Creates an `index.md` file using `markdown-index-template`.
+  * Breaking changes: Creates a `breaking.md` file using `markdown-breaking-template`.
+  * Deprecations: Creates a `deprecations.md` file using `markdown-deprecations-template`.
+
+# REQUIRED for breaking-change, deprecation, known-issue
+# impact:
+
+# REQUIRED for breaking-change, deprecation, known-issue
+# action:
+
+# REQUIRED for all kinds
+# Affected component; usually one of "elastic-agent", "fleet-server", "filebeat", "metricbeat", "auditbeat", "all", etc.
+component:
+
+# AUTOMATED
+# OPTIONAL to manually add other PR URLs
+# PR URL: A link the PR that added the changeset.
+# If not present is automatically filled by the tooling finding the PR where this changelog fragment has been added.
+# NOTE: the tooling supports backports, so it's able to fill the original PR number instead of the backport PR number.
+# Please provide it if you are adding a fragment for a different PR.
+pr:
+  - https://github.com/elastic/elastic-agent-changelog-tool/pull/213
+
+# AUTOMATED
+# OPTIONAL to manually add other issue URLs
+# Issue URL; optional; the GitHub issue related to this changeset (either closes or is part of).
+# If not present is automatically filled by the tooling with the issue linked to the PR number.
+# issue: https://github.com/owner/repo/1234

cmd/render.go

@@ -8,21 +8,17 @@ import (
 	"fmt"
 	"log"
 
-	"github.com/elastic/elastic-agent-changelog-tool/internal/assets"
 	"github.com/elastic/elastic-agent-changelog-tool/internal/changelog"
 	"github.com/spf13/afero"
 	"github.com/spf13/cobra"
 	"github.com/spf13/viper"
 )
 
-var RenderLongDescription = fmt.Sprintf(`Use this command to render the consolidated changelog.
+var RenderLongDescription = `Use this command to render the consolidated changelog.
 
 --version is required. Consolidated changelog version (x.y.z) in 'changelogs' folder
---template is optional. Specify full path to your template file or use predefined templates. Default: asciidoc-embedded
-
-Predefined templates:
-%s
-`, assets.GetEmbeddedTemplates().String())
+--file_type is optional. Specify the file_type: 'asciidoc' or 'markdown'
+--template is optional. Specify full path to your template file or use predefined templates. Default: asciidoc-embedded`
 
 func RenderCmd(fs afero.Fs) *cobra.Command {
 	renderCmd := &cobra.Command{
@@ -35,12 +31,18 @@ func RenderCmd(fs afero.Fs) *cobra.Command {
 		RunE: func(cmd *cobra.Command, args []string) error {
 			dest := viper.GetString("changelog_destination")
 			renderedDest := viper.GetString("rendered_changelog_destination")
+			repo := viper.GetString("repo")
 
 			version, err := cmd.Flags().GetString("version")
 			if err != nil {
 				return fmt.Errorf("error parsing flag 'version': %w", err)
 			}
 
+			file_type, err := cmd.Flags().GetString("file_type")
+			if err != nil {
+				return fmt.Errorf("error parsing flag 'file_type': %w", err)
+			}
+
 			template, err := cmd.Flags().GetString("template")
 			if err != nil {
 				return fmt.Errorf("error parsing flag 'template': %w", err)
@@ -51,16 +53,36 @@ func RenderCmd(fs afero.Fs) *cobra.Command {
 				return fmt.Errorf("error loading changelog from file: %w", err)
 			}
 
-			r := changelog.NewRenderer(fs, c, renderedDest, template)
-
-			if err := r.Render(); err != nil {
-				return fmt.Errorf("cannot build asciidoc file: %w", err)
+			if file_type == "asciidoc" {
+				r := changelog.NewRenderer(fs, c, renderedDest, "asciidoc-embedded", repo)
+				if err := r.Render(); err != nil {
+					return fmt.Errorf("cannot build asciidoc file: %w", err)
+				}
+			} else if file_type == "markdown" {
+				r_index := changelog.NewRenderer(fs, c, renderedDest, "markdown-index", repo)
+				if err := r_index.Render(); err != nil {
+					return fmt.Errorf("cannot build markdown file: %w", err)
+				}
+				r_breaking := changelog.NewRenderer(fs, c, renderedDest, "markdown-breaking", repo)
+				if err := r_breaking.Render(); err != nil {
+					return fmt.Errorf("cannot build markdown file: %w", err)
+				}
+				r_deprecations := changelog.NewRenderer(fs, c, renderedDest, "markdown-deprecations", repo)
+				if err := r_deprecations.Render(); err != nil {
+					return fmt.Errorf("cannot build markdown file: %w", err)
+				}
+			} else {
+				r := changelog.NewRenderer(fs, c, renderedDest, template, repo)
+				if err := r.Render(); err != nil {
+					return fmt.Errorf("cannot build file: %w", err)
+				}
 			}
 
 			return nil
 		},
 	}
 
+	renderCmd.Flags().String("file_type", viper.GetString("file_type"), "The file type of the rendered release notes: `asciidoc` or `markdown`")
 	renderCmd.Flags().String("template", viper.GetString("template"), "The template used to generate the changelog")
 	renderCmd.Flags().String("version", "", "The version of the consolidated changelog being created")
 	err := renderCmd.MarkFlagRequired("version")

config.changelog.yaml

@@ -0,0 +1,3 @@
+owner: elastic
+repo: elastic-agent-changelog-tool
+rendered_changelog_destination: changelog

docs/configuration.md

@@ -1,21 +1,29 @@
 # Configuration options
 
-`elastic-agent-changelog-tool` has configuration options available to change it's behaviour.
+`elastic-agent-changelog-tool` has configuration options available to change its behaviour.
 
-All settings are managed via the [`settings`][settings] package, using [`spf13/viper`][viper].  
+All settings are managed via the [`settings`][settings] package, using [`spf13/viper`][viper].
 Configurations are bound to environment variables with same name and `ELASTIC_AGENT_CHANGELOG` prefix using [`viper.BindEnv`][bindenv].
 
 This CLI supports and adhere to cross platform XDG Standard provided by [`OpenPeeDeeP/xdg`][xdg].
 
-|Settings key|Default value|Note|
+| Settings | Default value | Description |
 |---|---|---|
-|`fragment_location`|`$GIT_REPO_ROOT/changelog/fragments`|The location of changelog fragments used by the CLI. By default `fragment_root` + `fragment_path`.| 
+|`fragment_location`|`$GIT_REPO_ROOT/changelog/fragments`|The location of changelog fragments used by the CLI. By default `fragment_root` + `fragment_path`.|
 |`fragment_path`|`changelog/fragments`|The path in `fragment_root` where to locate changelog fragments.|
 |`fragment_root`|`$GIT_REPO_ROOT`|The root folder for `fragment_location`.|
 
 ## Configuration file
 
-Not supported yet.
+Add a `config.changelog.yaml` file to the repo where you're generating release notes.
+
+When generating Markdown files, at a minimum you should set the following settings:
+
+| Setting | Default value | Description |
+|---|---|---|
+| `owner` (required) | `elastic` | The owner of the GitHub repo. |
+| `repo` (required) | ‒ | The name of the GitHub repo. |
+| `rendered_changelog_destination` | `changelog` | The directory where you want to put the generated files.<br><br>When generating Markdown files, this should probably be `docs/release-notes/_snippets`. |
 
 ## Supported Environment Variables
 

docs/getting-started.md

@@ -25,6 +25,7 @@ $ elastic-agent-changelog-tool new "my test fragment"
 This will create `./changelog/fragments/<timestamp>-my-test-fragment.yaml` with this content:
 
 ```yaml
+# REQUIRED
 # Kind can be one of:
 # - breaking-change: a change to previously-documented behavior
 # - deprecation: functionality that is being removed in a later release
@@ -37,25 +38,39 @@ This will create `./changelog/fragments/<timestamp>-my-test-fragment.yaml` with
 # - other: does not fit into any of the other categories
 kind: feature
 
+# REQUIRED for all kinds
 # Change summary; a 80ish characters long description of the change.
-summary:
+summary: {{.Summary}}
 
+# REQUIRED for breaking-change, deprecation, known-issue
 # Long description; in case the summary is not enough to describe the change
 # this field accommodate a description without length limits.
-#description:
+# description:
 
+# REQUIRED for breaking-change, deprecation, known-issue
+# impact:
+
+# REQUIRED for breaking-change, deprecation, known-issue
+# action:
+
+# REQUIRED for all kinds
 # Affected component; usually one of "elastic-agent", "fleet-server", "filebeat", "metricbeat", "auditbeat", "all", etc.
 component:
 
-# PR URL; optional; the PR number that added the changeset.
+# AUTOMATED
+# OPTIONAL to manually add other PR URLs
+# PR URL: A link the PR that added the changeset.
 # If not present is automatically filled by the tooling finding the PR where this changelog fragment has been added.
 # NOTE: the tooling supports backports, so it's able to fill the original PR number instead of the backport PR number.
 # Please provide it if you are adding a fragment for a different PR.
-#pr: https://github.com/owner/repo/1234
+# pr: https://github.com/owner/repo/1234
 
+# AUTOMATED
+# OPTIONAL to manually add other issue URLs
 # Issue URL; optional; the GitHub issue related to this changeset (either closes or is part of).
 # If not present is automatically filled by the tooling with the issue linked to the PR number.
-#issue: https://github.com/owner/repo/1234
+# issue: https://github.com/owner/repo/1234
+
 ```
 
 Ensure `kind` is correct and fill the `summary` field with a brief description.
@@ -80,7 +95,7 @@ entries:
       kind: feature
       pr:
           - https://github.com/elastic/elastic-agent-changelog-tool/pull/13
-      issue: 
+      issue:
           - https://github.com/elastic/elastic-agent-changelog-tool/issues/21
       timestamp: 1649924282
       file:
@@ -93,12 +108,26 @@ There will be multiple entries, one for each files in `changelog/fragments`.
 
 ## 5. Render the consolidated changelog
 
-_Note_: at the moment there is only one renderer implemented: Asciidoc.
+### Markdown
+
+From the root folder of the repository run:
+
+```
+$ elastic-agent-changelog-tool render --version 0.1.0 --file_type markdown
+```
+
+This will create three files:
+
+* `./changelog/0.1.0/index.md`
+* `./changelog/0.1.0/breaking.md`
+* `./changelog/0.1.0/deprecations.md`
+
+### AsciiDoc
 
 From the root folder of the repository run:
 
 ```
-$ elastic-agent-changelog-tool render --version 0.1.0
+$ elastic-agent-changelog-tool render --version 0.1.0 --file_type asciidoc
 ```
 
 This will create `./changelog/0.1.0.asciidoc`.

docs/usage.md

@@ -43,11 +43,9 @@ $ elastic-agent-changelog-tool build --version=next --owner <owner> --repo <repo
 
 then render the consolidated changelog with:
 ```
-$ elastic-agent-changelog-tool render --version=next --template <template>
+$ elastic-agent-changelog-tool render --version=next --file_type <asciidoc|markdown>
 ```
 
-The template value can be chosen from a predefined internal list of templates (`render --help`) or use a full path to your template file.
-
 An example is [`../changelog/0.1.0.yaml`](../changelog/0.1.0.yaml).
 
 ### My PR does not need a changelog
@@ -82,9 +80,8 @@ $ elastic-agent-changelog-tool build --version=next --owner <owner> --repo <repo
 
 then render the consolidated changelog with:
 ```
-$ $ elastic-agent-changelog-tool render --version=next --template <template>
+$ elastic-agent-changelog-tool render --version=next --file_type <asciidoc|markdown>
 ```
-The template value can be chosen from a predefined internal list of templates (`render --help`) or use a full path to your template file.
 
 An example is [`../changelog/0.1.0.yaml`](../changelog/0.1.0.yaml).
 
@@ -97,8 +94,14 @@ The side effect is that the changelog will include all entries from latest stabl
 
 1. Create consolidated changelog with `$ elastic-agent-changelog-tool build --version <version> --owner <owner> --repo <repo>`;
 * This will create `./changelog/x.y.z.yaml`;
-2. Create rendered changelog with `$ elastic-agent-changelog-tool render --version <version> --template <template>`;
-* This will generate an asciidoc file in the `changelog/` directory;
+2. Create rendered changelog with `$ elastic-agent-changelog-tool render --version <version> --file_type <asciidoc|markdown>`;
+
+    Depending on the specified `file_type`, this will generate the following files:
+    * `markdown`:
+      * Release notes: `./changelog/<version>/index.md`
+      * Breaking changes: `./changelog/<version>/breaking.md`
+      * Deprecations: `./changelog/<version>/deprecations.md`
+    * `asciidoc`: `changelog/<version>.asciidoc`
 3. Use the rendered changelog.
 
 **Note**: we do not remove fragments, as they will be needed for the stable release version changelog.
@@ -111,30 +114,39 @@ The side effect is that the changelog will include all entries from latest stabl
 
 These steps require [GitHub Authentication](./github-authentication.md).
 
-* Wait for the last BC of the release. If another BC is generated after that or a patch version for a previous minor is released, you might need to restart the process.
-* Create a branch **from the commit of the BC**.
-* From the root folder of the repository run:
-
-```
-$ elastic-agent-changelog-tool build --version x.y.z --owner <owner> --repo <repo>
-```
-* Where:
-  * `x.y.z` is the version to release.
-  * `owner` is the user / organization the repository to use belongs to. The default value is `elastic`.
-  * `repo` is the name of the repository containing the issues / PRs, etc. The default value is `elastic-agent`.
-* This will create `./changelog/x.y.z.yaml`.
-* From the root of the repository run:
-```
-$ elastic-agent-changelog-tool cleanup
-```
-* Commit the previous changes (consolidated changelod and removed files)
-* From the root folder of the repository run:
-```
-$ elastic-agent-changelog-tool render --version x.y.z --template <template>
-```
-* This will generate an asciidoc fragment in the `changelog/` directory.
-* Integrate the generated fragment into the changelog. If the changelog is stored in the same repository, commit the changes in this same branch.
-* Create a PR with the changes to the `x.y` branch.
+1. Wait for the last BC of the release. If another BC is generated after that or a patch version for a previous minor is released, you might need to restart the process.
+1. Create a branch **from the commit of the BC**.
+1. From the root folder of the repository run:
+
+    ```
+    $ elastic-agent-changelog-tool build --version x.y.z --owner <owner> --repo <repo>
+    ```
+
+    Where:
+
+    * `x.y.z` is the version to release.
+    * `owner` is the user / organization the repository to use belongs to. The default value is `elastic`.
+    * `repo` is the name of the repository containing the issues / PRs, etc. The default value is `elastic-agent`.
+
+    This will create `./changelog/x.y.z.yaml`.
+1. From the root of the repository run:
+    ```
+    $ elastic-agent-changelog-tool cleanup
+    ```
+1. Commit the previous changes (consolidated changelod and removed files)
+1. From the root folder of the repository run:
+    ```
+    $ elastic-agent-changelog-tool render --version x.y.z --file_type <asciidoc|markdown>
+    ```
+
+    Depending on the specified `file_type`, this will generate the following files:
+    * `markdown`:
+      * Release notes: `./changelog/<version>/index.md`
+      * Breaking changes: `./changelog/<version>/breaking.md`
+      * Deprecations: `./changelog/<version>/deprecations.md`
+    * `asciidoc`: `changelog/<version>.asciidoc`
+1. Integrate the generated fragment into the changelog. If the changelog is stored in the same repository, commit the changes in this same branch.
+1. Create a PR with the changes to the `x.y` branch.
 
 
 ### On Release Day

go.mod

@@ -13,7 +13,6 @@ require (
 	github.com/spf13/viper v1.19.0
 	github.com/stretchr/testify v1.10.0
 	golang.org/x/oauth2 v0.24.0
-	golang.org/x/text v0.21.0
 	gopkg.in/yaml.v3 v3.0.1
 )
 
@@ -40,6 +39,7 @@ require (
 	golang.org/x/exp v0.0.0-20240416160154-fe59bbe5cc7f // indirect
 	golang.org/x/net v0.24.0 // indirect
 	golang.org/x/sys v0.19.0 // indirect
+	golang.org/x/text v0.21.0 // indirect
 	gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c // indirect
 	gopkg.in/ini.v1 v1.67.0 // indirect
 	gopkg.in/yaml.v2 v2.4.0 // indirect