Support custom summary.tmpl file (#501)

* Support custom summary.tmpl file

.chloggen/custom-changelog-template.yaml

@@ -0,0 +1,18 @@
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: enhancement
+
+# The name of the component, or a single word describing the area of concern, (e.g. crosslink)
+component: chloggen
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: support a custom changelog summary template
+
+# One or more tracking issues related to the change
+issues: [501]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext: |
+  The changelog summary template can be customized by configuring a custom template with the `summary_template` configuration setting.
+  The default template provides a starting point for a custom template: https://github.com/open-telemetry/opentelemetry-go-build-tools/blob/v0.13.0/chloggen/internal/chlog/summary.tmpl

chloggen/cmd/update.go

@@ -46,7 +46,7 @@ func updateCmd() *cobra.Command {
 			}
 
 			for changeLogKey, entries := range entriesByChangelog {
-				chlogUpdate, err := chlog.GenerateSummary(version, entries)
+				chlogUpdate, err := chlog.GenerateSummary(version, entries, globalCfg)
 				if err != nil {
 					return err
 				}

chloggen/internal/chlog/entry.go

@@ -104,23 +104,6 @@ func (e Entry) Validate(requireChangelog bool, components []string, validChangeL
 	return nil
 }
 
-func (e Entry) String() string {
-	issueStrs := make([]string, 0, len(e.Issues))
-	for _, issue := range e.Issues {
-		issueStrs = append(issueStrs, fmt.Sprintf("#%d", issue))
-	}
-	issueStr := strings.Join(issueStrs, ", ")
-
-	var sb strings.Builder
-	sb.WriteString(fmt.Sprintf("- `%s`: %s (%s)", e.Component, e.Note, issueStr))
-	if e.SubText != "" {
-		sb.WriteString("\n  ")
-		lines := strings.Split(strings.ReplaceAll(e.SubText, "\r\n", "\n"), "\n")
-		sb.WriteString(strings.Join(lines, "\n  "))
-	}
-	return sb.String()
-}
-
 func ReadEntries(cfg *config.Config) (map[string][]*Entry, error) {
 	yamlFiles, err := filepath.Glob(filepath.Join(cfg.EntriesDir, "*.yaml"))
 	if err != nil {
@@ -146,6 +129,7 @@ func ReadEntries(cfg *config.Config) (map[string][]*Entry, error) {
 		if err = yaml.Unmarshal(fileBytes, entry); err != nil {
 			return nil, err
 		}
+		entry.SubText = strings.ReplaceAll(entry.SubText, "\r\n", "\n")
 
 		if len(entry.ChangeLogs) == 0 {
 			for _, cl := range cfg.DefaultChangeLogs {

chloggen/internal/chlog/entry_test.go

@@ -15,9 +15,11 @@
 package chlog
 
 import (
+	"bytes"
 	"os"
 	"path/filepath"
 	"testing"
+	"text/template"
 
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
@@ -27,6 +29,13 @@ import (
 )
 
 func TestEntry(t *testing.T) {
+	tmpl := template.Must(
+		template.
+			New("summary.tmpl").
+			Funcs(TemplateFuncMap()).
+			Option("missingkey=error").
+			Parse(string(defaultTmpl)))
+
 	testCases := []struct {
 		name             string
 		entry            Entry
@@ -130,6 +139,17 @@ func TestEntry(t *testing.T) {
 			},
 			toString: "- `foo`: broke foo (#123)\n  more details",
 		},
+		{
+			name: "multiline subtext",
+			entry: Entry{
+				ChangeType: "breaking",
+				Component:  "foo",
+				Note:       "broke foo",
+				Issues:     []int{123},
+				SubText:    "more details\nsecond line",
+			},
+			toString: "- `foo`: broke foo (#123)\n  more details\n  second line",
+		},
 		{
 			name: "required_changelog",
 			entry: Entry{
@@ -223,7 +243,11 @@ func TestEntry(t *testing.T) {
 				return
 			}
 			assert.NoError(t, err)
-			assert.Equal(t, tc.toString, tc.entry.String())
+
+			buf := bytes.Buffer{}
+			err = tmpl.ExecuteTemplate(&buf, "entry", tc.entry)
+			assert.NoError(t, err)
+			assert.Equal(t, tc.toString, buf.String())
 		})
 	}
 

chloggen/internal/chlog/summary.go

@@ -18,57 +18,77 @@ import (
 	"bytes"
 	_ "embed"
 	"fmt"
-	"sort"
+	"path/filepath"
+	"strings"
 	"text/template"
+
+	"go.opentelemetry.io/build-tools/chloggen/internal/config"
 )
 
 //go:embed summary.tmpl
-var tmpl []byte
+var defaultTmpl []byte
 
 type summary struct {
 	Version         string
-	BreakingChanges []string
-	Deprecations    []string
-	NewComponents   []string
-	Enhancements    []string
-	BugFixes        []string
+	BreakingChanges []*Entry
+	Deprecations    []*Entry
+	NewComponents   []*Entry
+	Enhancements    []*Entry
+	BugFixes        []*Entry
 }
 
-func GenerateSummary(version string, entries []*Entry) (string, error) {
+func GenerateSummary(version string, entries []*Entry, cfg *config.Config) (string, error) {
 	s := summary{
 		Version: version,
 	}
 
 	for _, entry := range entries {
 		switch entry.ChangeType {
 		case Breaking:
-			s.BreakingChanges = append(s.BreakingChanges, entry.String())
+			s.BreakingChanges = append(s.BreakingChanges, entry)
 		case Deprecation:
-			s.Deprecations = append(s.Deprecations, entry.String())
+			s.Deprecations = append(s.Deprecations, entry)
 		case NewComponent:
-			s.NewComponents = append(s.NewComponents, entry.String())
+			s.NewComponents = append(s.NewComponents, entry)
 		case Enhancement:
-			s.Enhancements = append(s.Enhancements, entry.String())
+			s.Enhancements = append(s.Enhancements, entry)
 		case BugFix:
-			s.BugFixes = append(s.BugFixes, entry.String())
+			s.BugFixes = append(s.BugFixes, entry)
 		}
 	}
 
-	s.BreakingChanges = sort.StringSlice(s.BreakingChanges)
-	s.Deprecations = sort.StringSlice(s.Deprecations)
-	s.NewComponents = sort.StringSlice(s.NewComponents)
-	s.Enhancements = sort.StringSlice(s.Enhancements)
-	s.BugFixes = sort.StringSlice(s.BugFixes)
+	return s.String(cfg.SummaryTemplate)
+}
 
-	return s.String()
+func TemplateFuncMap() template.FuncMap {
+	return template.FuncMap{
+		"indent": func(n int, s string) string {
+			indent := strings.Repeat(" ", n)
+			return indent + strings.ReplaceAll(s, "\n", "\n"+indent)
+		},
+	}
 }
 
-func (s summary) String() (string, error) {
-	tmpl := template.Must(
-		template.
+func (s summary) String(summaryTemplate string) (string, error) {
+	var tmpl *template.Template
+	var err error
+
+	if summaryTemplate != "" {
+		tmpl, err = template.
+			New(filepath.Base(summaryTemplate)).
+			Funcs(TemplateFuncMap()).
+			Option("missingkey=error").
+			ParseFiles(summaryTemplate)
+	} else {
+		tmpl, err = template.
 			New("summary.tmpl").
+			Funcs(TemplateFuncMap()).
 			Option("missingkey=error").
-			Parse(string(tmpl)))
+			Parse(string(defaultTmpl))
+	}
+	if err != nil {
+		return "", err
+	}
 
 	buf := bytes.Buffer{}
 	if err := tmpl.Execute(&buf, s); err != nil {

chloggen/internal/chlog/summary.tmpl

@@ -1,4 +1,15 @@
-
+{{- define "entry" -}}
+- `{{ .Component }}`: {{ .Note }} (
+{{- range $i, $issue := .Issues }}
+{{- if $i }}, {{ end -}}
+#{{ $issue }}
+{{- end -}}
+)
+
+{{- if .SubText }}
+{{ .SubText | indent 2 }}
+{{- end }}
+{{- end }}
 ## {{ .Version }}
 
 {{- if .BreakingChanges }}
@@ -8,7 +19,7 @@
 {{- range $i, $change := .BreakingChanges }}
 {{- if eq $i 0}}
 {{end}}
-{{ $change }}
+{{ template "entry" $change }}
 {{- end }}
 {{- end }}
 
@@ -19,7 +30,7 @@
 {{- range $i, $change := .Deprecations }}
 {{- if eq $i 0}}
 {{end}}
-{{ $change }}
+{{ template "entry" $change }}
 {{- end }}
 {{- end }}
 
@@ -30,7 +41,7 @@
 {{- range $i, $change := .NewComponents }}
 {{- if eq $i 0}}
 {{end}}
-{{ $change }}
+{{ template "entry" $change }}
 {{- end }}
 {{- end }}
 
@@ -41,7 +52,7 @@
 {{- range $i, $change := .Enhancements }}
 {{- if eq $i 0}}
 {{end}}
-{{ $change }}
+{{ template "entry" $change }}
 {{- end }}
 {{- end }}
 
@@ -52,6 +63,6 @@
 {{- range $i, $change := .BugFixes }}
 {{- if eq $i 0}}
 {{end}}
-{{ $change }}
+{{ template "entry" $change }}
 {{- end }}
 {{- end }}

chloggen/internal/chlog/summary_test.go

@@ -21,6 +21,8 @@ import (
 
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
+
+	"go.opentelemetry.io/build-tools/chloggen/internal/config"
 )
 
 func TestSummary(t *testing.T) {
@@ -91,7 +93,7 @@ func TestSummary(t *testing.T) {
 		SubText:    "more details",
 	}
 
-	actual, err := GenerateSummary("1.0", []*Entry{&brk1, &brk2, &dep1, &dep2, &enh1, &enh2, &bug1, &bug2, &new1, &new2})
+	actual, err := GenerateSummary("1.0", []*Entry{&brk1, &brk2, &dep1, &dep2, &enh1, &enh2, &bug1, &bug2, &new1, &new2}, &config.Config{})
 	assert.NoError(t, err)
 
 	// This file is not meant to be the entire changelog so will not pass markdownlint if named with .md extension.
@@ -100,3 +102,28 @@ func TestSummary(t *testing.T) {
 
 	assert.Equal(t, string(expected), actual)
 }
+
+func TestCustomSummary(t *testing.T) {
+	brk1 := Entry{
+		ChangeType: Breaking,
+		Component:  "foo",
+		Note:       "broke foo",
+		Issues:     []int{123},
+	}
+	brk2 := Entry{
+		ChangeType: Breaking,
+		Component:  "bar",
+		Note:       "broke bar",
+		Issues:     []int{345, 678},
+		SubText:    "more details",
+	}
+
+	actual, err := GenerateSummary("1.0", []*Entry{&brk1, &brk2}, &config.Config{SummaryTemplate: filepath.Join("testdata", "custom.tmpl")})
+	require.NoError(t, err)
+
+	// This file is not meant to be the entire changelog so will not pass markdownlint if named with .md extension.
+	expected, err := os.ReadFile(filepath.Join("testdata", "CHANGELOG_custom"))
+	require.NoError(t, err)
+
+	assert.Equal(t, string(expected), actual)
+}

chloggen/internal/chlog/testdata/CHANGELOG_custom

@@ -0,0 +1,8 @@
+
+## 1.0
+
+### 🛑 Breaking changes 🛑
+
+- `foo`: broke foo ([#123](https://github.com/open-telemetry/opentelemetry-go-build-tools/issues/123))
+- `bar`: broke bar ([#345](https://github.com/open-telemetry/opentelemetry-go-build-tools/issues/345), [#678](https://github.com/open-telemetry/opentelemetry-go-build-tools/issues/678))
+  more details