Document jreleaser/jreleaser#461

jreleaser · Dec 2, 2022 · ba10ee0 · ba10ee0
1 parent d8f2b55
commit ba10ee0
Show file tree

Hide file tree

Showing 6 changed files with 293 additions and 5 deletions.
diff --git 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.
+
+<!-- JRELEASER_CHANGELOG_APPEND - Do not remove or modify this section -->
+----
+
+The updated changelog for a `1.0.0` releas would look like this
+
+[source]
+.CHANGELOG.md
+----
+# Changelog
+
+Lorem isum dolor sit amet.
+
+<!-- JRELEASER_CHANGELOG_APPEND - Do not remove or modify this section -->
+## [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
@@ -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
@@ -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
@@ -65,9 +65,23 @@
         -->
         <format>- {{commitShortHash}} {{commitTitle}}</format>
 
+        <!--
+          The template to use for category titles.
+          Defaults to `## {{categoryTitle}}`.
+          icon:dot-circle[] icon:file-alt[]
+        -->
+        <categoryTitleFormat>### {{categoryTitle}}</categoryTitleFormat>
+
+        <!--
+          The template to use for the contributors section.
+          Defaults to `## Contributors`.
+          icon:dot-circle[] icon:file-alt[]
+        -->
+        <contributorsTitleFormat>### Contributors'</contributorsTitleFormat>
+
         <!--
           The template to use for the whole changelog.
-          Defaults is shown.
+          Default is shown.
           icon:dot-circle[] icon:file-alt[]
         -->
         <content>
@@ -85,6 +99,50 @@
         -->
         <contentTemplate>path/to/template/changelog.tpl</contentTemplate>
 
+        <!--
+          icon:dot-circle[]
+        -->
+        <append>
+          <!--
+            Enables appending to an existing changelog file.
+            Defaults to `false`.
+            icon:dot-circle[]
+          -->
+          <enabled>true</enabled>
+
+          <!--
+            The title for the partial changelog.
+            Default is shown.
+            icon:dot-circle[] icon:file-alt[]
+          -->
+          <title>## [{{tagName}}]</title>
+
+          <!--
+            Path to the full changelog file where appends will occur.
+            Default is shown.
+            icon:dot-circle[] icon:file-alt[]
+          -->
+          <target>CHANGELOG.md</target>
+
+          <!--
+            The template to use for the partial changelog.
+            Default is shown.
+            icon:dot-circle[] icon:file-alt[]
+          -->
+          <content>
+            {{changelogTitle}}
+            {{changelogContent}}
+          </content>
+
+          <!--
+            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</contentTemplate>
+        </append>
+
         <!--
           icon:dot-circle[]
         -->

diff --git 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
@@ -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.