Support rendering description for breaking changes and known issues (#129)

* changelog: add newlines for readability

* changelog: add crossreferenceList template Fn

* changelog: support description in rendered changelog

* changelog: test description presence

* fragment: note when description is rendered

* add fragment

* fragment: update fragment in test

Author: endorama

changelog/fragments/1673258661-Support-rendering-description.yaml

@@ -0,0 +1,32 @@
+# 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: Support rendering description for breaking changes and known issues.
+
+# Long description; in case the summary is not enough to describe the change
+# this field accommodate a description without length limits.
+# NOTE: This field will be rendered only for breaking-change and known-issue kinds at the moment.
+#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

internal/assets/asciidoc-template.asciidoc

@@ -17,6 +17,7 @@ Review important information about the {{.Component}} {{.Version}} release.
 {{- end }}
 {{- end }}
 {{- end }}
+
 {{ if .BreakingChange -}}
 [discrete]
 [[breaking-changes-{{.Version}}]]
@@ -30,10 +31,17 @@ impact to your application.
 {{ range $k, $v := .BreakingChange }}
 {{ $k | header2}}
 {{ range $item := $v }}
-* {{ $item.Summary | beautify }} {{ linkPRSource $item.Component $item.LinkedPR }} {{ linkIssueSource $item.Component $item.LinkedIssue }}
+[discrete]
+[[breaking-{{crossreferenceList $item.LinkedPR}}]]
+.{{ $item.Summary | beautify }} {{ linkPRSource $item.Component $item.LinkedPR }} {{ linkIssueSource $item.Component $item.LinkedIssue }}
+[%collapsible]
+====
+{{ $item.Description }}
+====
 {{- end }}
 {{- end }}
 {{- end }}
+
 {{ if .KnownIssue -}}
 [discrete]
 [[known-issues-{{.Version}}]]
@@ -43,10 +51,17 @@ impact to your application.
 {{ range $k, $v := .KnownIssue }}
 {{ $k | header2}}
 {{ range $item := $v }}
-* {{ $item.Summary | beautify }} {{ linkPRSource $item.Component $item.LinkedPR }} {{ linkIssueSource $item.Component $item.LinkedIssue }}
+[discrete]
+[[known-issue-issue-{{crossreferenceList $item.LinkedIssue}}]]
+.{{ $item.Summary | beautify }} {{ linkPRSource $item.Component $item.LinkedPR }} {{ linkIssueSource $item.Component $item.LinkedIssue }}
+[%collapsible]
+====
+{{ $item.Description }}
+====
 {{- end }}
 {{- end }}
 {{- end }}
+
 {{ if .Deprecation -}}
 [discrete]
 [[deprecations-{{.Version}}]]
@@ -64,6 +79,7 @@ upgrade to {{.Version}}.
 {{- end }}
 {{- end }}
 {{- end }}
+
 {{ if .Feature -}}
 [discrete]
 [[new-features-{{.Version}}]]
@@ -78,6 +94,7 @@ The {{.Version}} release adds the following new and notable features.
 {{- end }}
 {{- end }}
 {{- end }}
+
 {{ if .Enhancement }}
 [discrete]
 [[enhancements-{{.Version}}]]
@@ -90,6 +107,7 @@ The {{.Version}} release adds the following new and notable features.
 {{- end }}
 {{- end }}
 {{- end }}
+
 {{ if .BugFix }}
 [discrete]
 [[bug-fixes-{{.Version}}]]
@@ -103,4 +121,4 @@ The {{.Version}} release adds the following new and notable features.
 {{- end }}
 {{- end }}
 
-// end {{.Version}} relnotes
+// end {{.Version}} relnotes

internal/changelog/fragment/creator_internal_test.go

@@ -89,6 +89,7 @@ summary: foobar
 
 # Long description; in case the summary is not enough to describe the change
 # this field accommodate a description without length limits.
+# NOTE: This field will be rendered only for breaking-change and known-issue kinds at the moment.
 #description:
 
 # Affected component; a word indicating the component this changeset affects.

internal/changelog/fragment/template.yaml

@@ -15,6 +15,7 @@ summary: {{.Summary}}
 
 # Long description; in case the summary is not enough to describe the change
 # this field accommodate a description without length limits.
+# NOTE: This field will be rendered only for breaking-change and known-issue kinds at the moment.
 #description:
 
 # Affected component; a word indicating the component this changeset affects.

internal/changelog/renderer.go

@@ -77,6 +77,9 @@ func (r Renderer) Render() error {
 
 	tmpl, err := template.New("release-notes").
 		Funcs(template.FuncMap{
+			"crossreferenceList": func(ids []string) string {
+				return strings.Join(ids, "-")
+			},
 			// nolint:staticcheck // ignoring for now, supports for multiple component is not implemented
 			"linkPRSource": func(component string, ids []string) string {
 				res := make([]string, len(ids))

internal/changelog/renderer_test.go

@@ -48,10 +48,11 @@ func TestRenderer(t *testing.T) {
 		switch e.Kind {
 		// NOTE: this is the list of kinds of entries we expect to see
 		// in the rendered changelog (not all kinds are expected)
-		case changelog.BreakingChange, changelog.Deprecation,
-			changelog.BugFix, changelog.Enhancement,
-			changelog.Feature, changelog.KnownIssue,
-			changelog.Security:
+		case changelog.BreakingChange, changelog.KnownIssue:
+			require.Contains(t, strings.ToLower(string(out)), e.Summary)
+			require.Contains(t, string(out), e.Description)
+		case changelog.Deprecation, changelog.BugFix, changelog.Enhancement,
+			changelog.Feature, changelog.Security:
 			require.Contains(t, strings.ToLower(string(out)), e.Summary)
 		default:
 			require.NotContains(t, strings.ToLower(string(out)), e.Summary)

internal/changelog/testdata/1648040928-breaking-change.yaml

@@ -1,2 +1,5 @@
 kind: breaking-change
 summary: a breaking change
+description: This paragraph to describe details and impact of this breaking change
+pr: 1234
+component: whatever

internal/changelog/testdata/1648040928-known-issue.yaml

@@ -1,2 +1,5 @@
 kind: known-issue
 summary: a known issue
+description: This paragraph to describe details and impact of this known issue
+issue: 1234
+component: whatever