From ba10ee080c1bc5bfec753b673d14a5441ba6282a Mon Sep 17 00:00:00 2001 From: Andres Almiray Date: Wed, 16 Nov 2022 13:03:04 +0200 Subject: [PATCH] Document https://github.com/jreleaser/jreleaser/issues/461 --- .../reference/pages/release/changelog.adoc | 72 +++++++++++++++++++ .../partials/release/gradle/changelog.adoc | 41 ++++++++++- .../partials/release/json/changelog.adoc | 41 ++++++++++- .../partials/release/maven/changelog.adoc | 60 +++++++++++++++- .../partials/release/toml/changelog.adoc | 42 ++++++++++- .../partials/release/yaml/changelog.adoc | 42 ++++++++++- 6 files changed, 293 insertions(+), 5 deletions(-) diff --git a/docs/modules/reference/pages/release/changelog.adoc b/docs/modules/reference/pages/release/changelog.adoc index f730ca6d0..796b33b94 100644 --- a/docs/modules/reference/pages/release/changelog.adoc +++ b/docs/modules/reference/pages/release/changelog.adoc @@ -453,3 +453,75 @@ For a project with the following commits Generates a changelog similar to image::ROOT:jreleaser-changelog-preset-gitmoji.png[] + +== Appending + +JReleaser may append the changelog for a given release to an existing changelog (typically `CHANGELOG.md` at the root of +the project). This can be achieved by enabling the `append` block, for example + +[source,yaml] +[subs="attributes,+macros"] +---- +release: + github: + changelog: + formatted: always + categoryTitleFormat: '#### {{categoryTitle}}' + contributorsTitleFormat: '#### Contributors' + preset: conventional-commits + append: + enabled: true +---- + +Given an initial `CHANGELOG.md` such as + +[source] +.CHANGELOG.md +---- +# Changelog + +Lorem isum dolor sit amet. + + +---- + +The updated changelog for a `1.0.0` releas would look like this + +[source] +.CHANGELOG.md +---- +# Changelog + +Lorem isum dolor sit amet. + + +## [v1.0.0] + +### Changelog + +#### 🛠 Build +- 2454d3a Add arguments to Main class (Andres Almiray) +- 9797539 Use fetch-depth=0 when checking out on release (Andres Almiray) +- ca15da0 Add Maven assembly descriptor (Andres Almiray) +- 8270c4f Setup build & release workflows (Andres Almiray) +- 1442ef0 Add JReleaser configuration (Andres Almiray) +- 839fab8 Add Maven wrapper files (Andres Almiray) +- 0cd14e9 Add sources (Andres Almiray) +- fd17794 Add license file (Andres Almiray) + +--- +- 51c3234 Init repository (Andres Almiray) + + +#### Contributors +We'd like to thank the following people for their contributions: +Andres Almiray +---- + +Note the use of a special comment as anchor for finding the right place to append the generated changelog. If the anchor +does not exist then the generated changelog will be prepended at the beginning of the full changelog. + +NOTE: Changelog appending is only active when a project is not snapshot. + +IMPORTANT: JReleaser does not verify if a previous tag is already found in the full changelog before appending. + diff --git a/docs/modules/reference/partials/release/gradle/changelog.adoc b/docs/modules/reference/partials/release/gradle/changelog.adoc index e874a0cec..37784ca1e 100644 --- a/docs/modules/reference/partials/release/gradle/changelog.adoc +++ b/docs/modules/reference/partials/release/gradle/changelog.adoc @@ -46,8 +46,18 @@ // icon:dot-circle[] icon:file-alt[] format = '- {{commitShortHash}} {{commitTitle}}' + // The template to use for category titles. + // Defaults to `## {{categoryTitle}}`. + // icon:dot-circle[] icon:file-alt[] + categoryTitleFormat = '### {{categoryTitle}}' + + // The template to use for the contributors section. + // Defaults to `## Contributors`. + // icon:dot-circle[] icon:file-alt[] + contributorsTitleFormat = '### Contributors' + // The template to use for the whole changelog. - // Defaults is shown. + // Default is shown. // icon:dot-circle[] icon:file-alt[] content = '#Changelog\n\n{{changelogChanges}}\n{{changelogContributors}}' @@ -57,6 +67,35 @@ // icon:dot-circle[] contentTemplate = 'path/to/template/changelog.tpl' + // icon:dot-circle[] + append { + // Enables appending to an existing changelog file. + // Defaults to `false`. + // icon:dot-circle[] + enabled = true + + // The title for the partial changelog. + // Default is shown. + // icon:dot-circle[] icon:file-alt[] + title = '## [{{tagName}}]' + + // Path to the full changelog file where appends will occur. + // Default is shown. + // icon:dot-circle[] icon:file-alt[] + target = 'CHANGELOG.md' + + // The template to use for the partial changelog. + // Default is shown. + // icon:dot-circle[] icon:file-alt[] + content = '{{changelogTitle}}\n{{changelogContent}}' + + // Path to a template file that defines the contents. + // Review the available xref:reference:name-templates.adoc[]. + // Defaults to `src/jreleaser/templates/append-changelog.tpl`. + // icon:dot-circle[] + contentTemplate = 'path/to/template/append-changelog.tpl' + } + // icon:dot-circle[] contributors { // Enables the contributors block. diff --git a/docs/modules/reference/partials/release/json/changelog.adoc b/docs/modules/reference/partials/release/json/changelog.adoc index 0c5d0cc43..1353ac01e 100644 --- a/docs/modules/reference/partials/release/json/changelog.adoc +++ b/docs/modules/reference/partials/release/json/changelog.adoc @@ -46,8 +46,18 @@ // icon:dot-circle[] icon:file-alt[] "format": "- {{commitShortHash}} {{commitTitle}}", + // The template to use for category titles. + // Defaults to `## {{categoryTitle}}`. + // icon:dot-circle[] icon:file-alt[] + "categoryTitleFormat": "### {{categoryTitle}}", + + // The template to use for the contributors section. + // Defaults to `## Contributors`. + // icon:dot-circle[] icon:file-alt[] + "contributorsTitleFormat": "### Contributors", + // The template to use for the whole changelog. - // Defaults is shown. + // Default is shown. // icon:dot-circle[] icon:file-alt[] "content": "#Changelog\n\n{{changelogChanges}}\n{{changelogContributors}}", @@ -57,6 +67,35 @@ // icon:dot-circle[] "contentTemplate": "path/to/template/changelog.tpl", + // icon:dot-circle[] + "append": { + // Enables appending to an existing changelog file. + // Defaults to `false`. + // icon:dot-circle[] + "enabled": true, + + // The title for the partial changelog. + // Default is shown. + // icon:dot-circle[] icon:file-alt[] + "title": "## [{{tagName}}]", + + // Path to the full changelog file where appends will occur. + // Default is shown. + // icon:dot-circle[] icon:file-alt[] + "target": "CHANGELOG.md", + + // The template to use for the partial changelog. + // Default is shown. + // icon:dot-circle[] icon:file-alt[] + "content": "{{changelogTitle}}\n{{changelogContent}}", + + // Path to a template file that defines the contents. + // Review the available xref:reference:name-templates.adoc[]. + // Defaults to `src/jreleaser/templates/append-changelog.tpl`. + // icon:dot-circle[] + "contentTemplate": "path/to/template/append-changelog.tpl" + }, + // icon:dot-circle[] "contributors": { // Enables the contributors block. diff --git a/docs/modules/reference/partials/release/maven/changelog.adoc b/docs/modules/reference/partials/release/maven/changelog.adoc index 97d08c692..93078742f 100644 --- a/docs/modules/reference/partials/release/maven/changelog.adoc +++ b/docs/modules/reference/partials/release/maven/changelog.adoc @@ -65,9 +65,23 @@ --> - {{commitShortHash}} {{commitTitle}} + + ### {{categoryTitle}} + + + ### Contributors' + @@ -85,6 +99,50 @@ --> path/to/template/changelog.tpl + + + + true + + + ## [{{tagName}}] + + + CHANGELOG.md + + + + {{changelogTitle}} + {{changelogContent}} + + + + path/to/template/append-changelog.tpl + + diff --git a/docs/modules/reference/partials/release/toml/changelog.adoc b/docs/modules/reference/partials/release/toml/changelog.adoc index 60bad128b..f89318fe3 100644 --- a/docs/modules/reference/partials/release/toml/changelog.adoc +++ b/docs/modules/reference/partials/release/toml/changelog.adoc @@ -45,8 +45,18 @@ # icon:dot-circle[] icon:file-alt[] changelog.format = "- {{commitShortHash}} {{commitTitle}}" + # The template to use for category titles. + # Defaults to `## {{categoryTitle}}`. + # icon:dot-circle[] icon:file-alt[] + changelog.categoryTitleFormat = "### {{categoryTitle}}" + + # The template to use for the contributors section. + # Defaults to `## Contributors`. + # icon:dot-circle[] icon:file-alt[] + changelog.contributorsTitleFormat = "### Contributors" + # The template to use for the whole changelog. - # Defaults is shown. + # Default is shown. # icon:dot-circle[] icon:file-alt[] changelog.content = """ # Changelog @@ -60,6 +70,36 @@ # icon:dot-circle[] changelog.contentTemplate = "path/to/template/changelog.tpl" + # icon:dot-circle[] + pass:[[[]release.{gitservice_id}.changelog.appendpass:[]]] + # Enables appending to an existing changelog file. + # Defaults to `false`. + # icon:dot-circle[] + enable = true + + # The title for the partial changelog. + # Default is shown. + # icon:dot-circle[] icon:file-alt[] + title = "## [{{tagName}}]" + + # Path to the full changelog file where appends will occur. + # Default is shown. + # icon:dot-circle[] icon:file-alt[] + target = "CHANGELOG.md" + + # The template to use for the partial changelog. + # Default is shown. + # icon:dot-circle[] icon:file-alt[] + content = """ + {{changelogTitle}} + {{changelogContent}}""" + + # Path to a template file that defines the contents. + # Review the available xref:reference:name-templates.adoc[]. + # Defaults to `src/jreleaser/templates/append-changelog.tpl`. + # icon:dot-circle[] + contentTemplate = "path/to/template/append-changelog.tpl" + # icon:dot-circle[] pass:[[[]release.{gitservice_id}.changelog.contributorspass:[]]] # Enables the contributors block. diff --git a/docs/modules/reference/partials/release/yaml/changelog.adoc b/docs/modules/reference/partials/release/yaml/changelog.adoc index cdf72abe3..b8eac04ac 100644 --- a/docs/modules/reference/partials/release/yaml/changelog.adoc +++ b/docs/modules/reference/partials/release/yaml/changelog.adoc @@ -46,8 +46,18 @@ # icon:dot-circle[] icon:file-alt[] format: '- {{commitShortHash}} {{commitTitle}}' + # The template to use for category titles. + # Defaults to `## {{categoryTitle}}`. + # icon:dot-circle[] icon:file-alt[] + categoryTitleFormat: '### {{categoryTitle}}' + + # The template to use for the contributors section. + # Defaults to `## Contributors`. + # icon:dot-circle[] icon:file-alt[] + contributorsTitleFormat: '### Contributors' + # The template to use for the whole changelog. - # Defaults is shown. + # Default is shown. # icon:dot-circle[] icon:file-alt[] content: | # Changelog @@ -61,6 +71,36 @@ # icon:dot-circle[] contentTemplate: path/to/template/changelog.tpl + # icon:dot-circle[] + append: + # Enables appending to an existing changelog file. + # Defaults to `false`. + # icon:dot-circle[] + enabled: true + + # The title for the partial changelog. + # Default is shown. + # icon:dot-circle[] icon:file-alt[] + title: '## [{{tagName}}]' + + # Path to the full changelog file where appends will occur. + # Default is shown. + # icon:dot-circle[] icon:file-alt[] + target: 'CHANGELOG.md' + + # The template to use for the partial changelog. + # Default is shown. + # icon:dot-circle[] icon:file-alt[] + content: | + {{changelogTitle}} + {{changelogContent}} + + # Path to a template file that defines the contents. + # Review the available xref:reference:name-templates.adoc[]. + # Defaults to `src/jreleaser/templates/append-changelog.tpl`. + # icon:dot-circle[] + contentTemplate: path/to/template/append-changelog.tpl + # icon:dot-circle[] contributors: # Enables the contributors block.