Provide custom template support for render (#118)

Author: lucian-ioan

changelog/fragments/1666881492-Custom-template-support-for-render.yaml

@@ -0,0 +1,31 @@
+# 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
+
+# Change summary; a 80ish characters long description of the change.
+summary: Custom template support for render
+
+# Long description; in case the summary is not enough to describe the change
+# this field accommodate a description without length limits.
+#description:
+
+# Affected component; a word indicating the component this changeset affects.
+component:
+
+# PR number; optional; the PR number 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: 1234
+
+# Issue number; 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: 1234

cmd/render.go

@@ -8,17 +8,27 @@ 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.
+
+--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())
+
 func RenderCmd(fs afero.Fs) *cobra.Command {
 	renderCmd := &cobra.Command{
 		Use:   "render",
 		Short: "Render a changelog in an asciidoc file",
-		Long:  "Render a changelog in an asciidoc file",
+		Long:  RenderLongDescription,
 		Args: func(cmd *cobra.Command, args []string) error {
 			return nil
 		},
@@ -31,12 +41,17 @@ func RenderCmd(fs afero.Fs) *cobra.Command {
 				return fmt.Errorf("error parsing flag 'version': %w", err)
 			}
 
+			template, err := cmd.Flags().GetString("template")
+			if err != nil {
+				return fmt.Errorf("error parsing flag 'template': %w", err)
+			}
+
 			c, err := changelog.FromFile(fs, fmt.Sprintf("./%s/%s.yaml", dest, version))
 			if err != nil {
 				return fmt.Errorf("error loading changelog from file: %w", err)
 			}
 
-			r := changelog.NewRenderer(fs, c, renderedDest)
+			r := changelog.NewRenderer(fs, c, renderedDest, template)
 
 			if err := r.Render(); err != nil {
 				return fmt.Errorf("cannot build asciidoc file: %w", err)
@@ -46,6 +61,7 @@ func RenderCmd(fs afero.Fs) *cobra.Command {
 		},
 	}
 
+	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")
 	if err != nil {

config.yaml

@@ -1,3 +1,4 @@
 owner: elastic
 repo: elastic-agent-changelog-tool
-components: [elastic-agent-changelog-tool]
+template: asciidoc-embedded
+components: [elastic-agent-changelog-tool]

docs/usage.md

@@ -39,12 +39,13 @@ From the repository root folder build the consolidated changelog with:
 $ elastic-agent-changelog-tool build --version=next --owner <owner> --repo <repo>
 ```
 
-the render the consolidated changelog with:
-
+then render the consolidated changelog with:
 ```
-$ elastic-agent-changelog-tool render --version=next --owner <owner> --repo <repo>
+$ elastic-agent-changelog-tool render --version=next --template <template>
 ```
 
+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
@@ -73,11 +74,11 @@ From the repository root folder build the consolidated changelog with:
 $ elastic-agent-changelog-tool build --version=next --owner <owner> --repo <repo>
 ```
 
-the render the consolidated changelog with:
-
+then render the consolidated changelog with:
 ```
-$ $ elastic-agent-changelog-tool render --version=next --owner <owner> --repo <repo>
+$ $ elastic-agent-changelog-tool render --version=next --template <template>
 ```
+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).
 
@@ -88,7 +89,7 @@ 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>`;
+2. Create rendered changelog with `$ elastic-agent-changelog-tool render --version <version> --template <template>`;
 * This will generate an asciidoc file in the `changelog/` directory;
 3. Use the rendered changelog.
 
@@ -119,7 +120,7 @@ $ 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
+$ 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.

…nal/changelog/asciidoc-template.asciidoc …ternal/assets/asciidoc-template.asciidocinternal/changelog/asciidoc-template.asciidoc renamed to internal/assets/asciidoc-template.asciidoc internal/changelog/asciidoc-template.asciidoc renamed to internal/assets/asciidoc-template.asciidoc

@@ -0,0 +1,34 @@
+// Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+// or more contributor license agreements. Licensed under the Elastic License 2.0;
+// you may not use this file except in compliance with the Elastic License 2.0.
+
+package assets
+
+import (
+	"embed"
+	"fmt"
+	"strings"
+)
+
+// Binds strings to the actual template file name
+// These strings can be used in the config template field or renderer template flag
+func GetEmbeddedTemplates() embeddedTemplates {
+	return map[string]string{
+		"asciidoc-embedded": "asciidoc-template.asciidoc",
+	}
+}
+
+//go:embed asciidoc-template.asciidoc
+var AsciidocTemplate embed.FS
+
+type embeddedTemplates map[string]string
+
+func (t embeddedTemplates) String() string {
+	var sb strings.Builder
+
+	for k := range t {
+		sb.WriteString(fmt.Sprintf("- %s\n", k))
+	}
+
+	return sb.String()
+}

internal/assets/assets.go

@@ -6,13 +6,13 @@ package changelog
 
 import (
 	"bytes"
-	"embed"
 	"fmt"
 	"html/template"
 	"log"
 	"path"
 	"strings"
 
+	"github.com/elastic/elastic-agent-changelog-tool/internal/assets"
 	"github.com/spf13/afero"
 	"github.com/spf13/viper"
 	"golang.org/x/text/cases"
@@ -23,14 +23,16 @@ type Renderer struct {
 	changelog Changelog
 	fs        afero.Fs
 	// dest is the destination location where the changelog is written to
-	dest string
+	dest  string
+	templ string
 }
 
-func NewRenderer(fs afero.Fs, c Changelog, dest string) *Renderer {
+func NewRenderer(fs afero.Fs, c Changelog, dest string, templ string) *Renderer {
 	return &Renderer{
 		changelog: c,
 		fs:        fs,
 		dest:      dest,
+		templ:     templ,
 	}
 }
 
@@ -132,13 +134,22 @@ func (r Renderer) Render() error {
 	return afero.WriteFile(r.fs, outFile, data.Bytes(), changelogFilePerm)
 }
 
-//go:embed asciidoc-template.asciidoc
-var asciidocTemplate embed.FS
-
 func (r Renderer) Template() ([]byte, error) {
-	data, err := asciidocTemplate.ReadFile("asciidoc-template.asciidoc")
+	var data []byte
+	var err error
+
+	if embeddedFileName, ok := assets.GetEmbeddedTemplates()[r.templ]; ok {
+		data, err = assets.AsciidocTemplate.ReadFile(embeddedFileName)
+		if err != nil {
+			return []byte{}, fmt.Errorf("cannot read embedded template: %s %w", embeddedFileName, err)
+		}
+
+		return data, nil
+	}
+
+	data, err = afero.ReadFile(r.fs, r.templ)
 	if err != nil {
-		return []byte{}, fmt.Errorf("cannot read embedded template: %w", err)
+		return []byte{}, fmt.Errorf("cannot read custom template: %w", err)
 	}
 
 	return data, nil

internal/changelog/renderer.go

@@ -34,7 +34,7 @@ func TestRenderer(t *testing.T) {
 	c, err := changelog.FromFile(fs, inFile)
 	require.NoError(t, err)
 
-	r := changelog.NewRenderer(fs, c, dest)
+	r := changelog.NewRenderer(fs, c, dest, "asciidoc-embedded")
 
 	err = r.Render()
 	require.Nil(t, err)

internal/changelog/renderer_test.go

@@ -60,6 +60,8 @@ func setDefaults() {
 
 	viper.SetDefault("changelog_destination", "changelog")
 	viper.SetDefault("rendered_changelog_destination", "changelog")
+
+	viper.SetDefault("template", "asciidoc-embedded")
 }
 
 func setConstants() {