diff --git a/changelog/fragments/1755717164-markdown.yaml b/changelog/fragments/1755717164-markdown.yaml new file mode 100644 index 0000000..4aaad53 --- /dev/null +++ b/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 diff --git a/cmd/render.go b/cmd/render.go index 85490fa..51399f5 100644 --- a/cmd/render.go +++ b/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'. Default: 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") diff --git a/config.changelog.yaml b/config.changelog.yaml new file mode 100644 index 0000000..82a8bca --- /dev/null +++ b/config.changelog.yaml @@ -0,0 +1,3 @@ +owner: elastic +repo: elastic-agent-changelog-tool +rendered_changelog_destination: changelog diff --git a/config.yaml b/config.yaml deleted file mode 100644 index c1edfdc..0000000 --- a/config.yaml +++ /dev/null @@ -1,4 +0,0 @@ -owner: elastic -repo: elastic-agent-changelog-tool -template: asciidoc-embedded -components: [elastic-agent-changelog-tool] diff --git a/docs/configuration.md b/docs/configuration.md index 15a099e..f108bf7 100644 --- a/docs/configuration.md +++ b/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.

When generating Markdown files, this should probably be `docs/release-notes/_snippets`. | ## Supported Environment Variables diff --git a/docs/getting-started.md b/docs/getting-started.md index da0039f..476d040 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -25,6 +25,7 @@ $ elastic-agent-changelog-tool new "my test fragment" This will create `./changelog/fragments/-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/-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`. diff --git a/docs/usage.md b/docs/usage.md index 790d18b..a76b15a 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -43,11 +43,9 @@ $ elastic-agent-changelog-tool build --version=next --owner --repo +$ elastic-agent-changelog-tool render --version=next --file_type ``` -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 --repo +$ elastic-agent-changelog-tool render --version=next --file_type ``` -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 --owner --repo `; * This will create `./changelog/x.y.z.yaml`; -2. Create rendered changelog with `$ elastic-agent-changelog-tool render --version --template