From 9c133b6a952abd72ea1e6e697311ee84367f02d1 Mon Sep 17 00:00:00 2001 From: Edoardo Tenani <526307+endorama@users.noreply.github.com> Date: Mon, 9 Jan 2023 11:37:04 +0100 Subject: [PATCH] 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 --- ...3258661-Support-rendering-description.yaml | 32 +++++++++++++++++++ internal/assets/asciidoc-template.asciidoc | 24 ++++++++++++-- .../fragment/creator_internal_test.go | 1 + internal/changelog/fragment/template.yaml | 1 + internal/changelog/renderer.go | 3 ++ internal/changelog/renderer_test.go | 9 +++--- .../testdata/1648040928-breaking-change.yaml | 3 ++ .../testdata/1648040928-known-issue.yaml | 3 ++ 8 files changed, 69 insertions(+), 7 deletions(-) create mode 100644 changelog/fragments/1673258661-Support-rendering-description.yaml diff --git a/changelog/fragments/1673258661-Support-rendering-description.yaml b/changelog/fragments/1673258661-Support-rendering-description.yaml new file mode 100644 index 0000000..16bf2cc --- /dev/null +++ b/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 diff --git a/internal/assets/asciidoc-template.asciidoc b/internal/assets/asciidoc-template.asciidoc index 167df83..c221735 100644 --- a/internal/assets/asciidoc-template.asciidoc +++ b/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 \ No newline at end of file +// end {{.Version}} relnotes diff --git a/internal/changelog/fragment/creator_internal_test.go b/internal/changelog/fragment/creator_internal_test.go index 1c996ca..e766c86 100644 --- a/internal/changelog/fragment/creator_internal_test.go +++ b/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. diff --git a/internal/changelog/fragment/template.yaml b/internal/changelog/fragment/template.yaml index c530ce7..0de6bac 100644 --- a/internal/changelog/fragment/template.yaml +++ b/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. diff --git a/internal/changelog/renderer.go b/internal/changelog/renderer.go index d6d5aec..48ea049 100644 --- a/internal/changelog/renderer.go +++ b/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)) diff --git a/internal/changelog/renderer_test.go b/internal/changelog/renderer_test.go index 9394679..787ad9f 100644 --- a/internal/changelog/renderer_test.go +++ b/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) diff --git a/internal/changelog/testdata/1648040928-breaking-change.yaml b/internal/changelog/testdata/1648040928-breaking-change.yaml index 655bf8a..b0af39f 100644 --- a/internal/changelog/testdata/1648040928-breaking-change.yaml +++ b/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 diff --git a/internal/changelog/testdata/1648040928-known-issue.yaml b/internal/changelog/testdata/1648040928-known-issue.yaml index 65ce52d..bbc55dd 100644 --- a/internal/changelog/testdata/1648040928-known-issue.yaml +++ b/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