refactor(config)!: revamp configuration

.github/actions/run-fixtures-test/action.yml

@@ -1,54 +1,74 @@
-name: Run a fixtures test
-description: Run a fixtures test
-
-inputs:
-  fixtures-dir:
-    description: Path to the fixtures directory
-    required: true
-  command:
-    description: The git-cliff command to run
-    required: false
-    default: ""
-  date-format:
-    description: The date format to use
-    required: false
-    default: "%Y-%m-%d"
-
-runs:
-  using: composite
-  steps:
-    - name: Install toolchain
-      uses: dtolnay/rust-toolchain@nightly
-
-    - name: Install git-cliff
-      run: cargo install --path git-cliff/
-      shell: bash
-
-    - name: Set git config
-      run: |
-        git config --global user.name "github-actions[bot]"
-        git config --global user.email "github-actions[bot]@users.noreply.github.com"
-      shell: bash
-
-    - name: Create commits and tags
-      working-directory: ${{ inputs.fixtures-dir }}
-      run: |
-        git init
-        ./commit.sh
-      shell: bash
-
-    - name: Generate a changelog
-      working-directory: ${{ inputs.fixtures-dir }}
-      run: git cliff --config cliff.toml ${{ inputs.command }} > output.md
-      shell: bash
-
-    - name: Compare the output with the expected output
-      working-directory: ${{ inputs.fixtures-dir }}
-      env:
-        IN_DATE_FORMAT: ${{ inputs.date-format }}
-      run: |
-        cat output.md
-        current_date=$(date +"$IN_DATE_FORMAT")
-        sed -i "s/<<DATE>>/$current_date/g" expected.md
-        diff --strip-trailing-cr output.md expected.md
-      shell: bash
+name: Run a fixtures test
+description: Run a fixtures test
+
+inputs:
+  fixtures-dir:
+    description: Path to the fixtures directory
+    required: true
+  command:
+    description: The git-cliff command to run
+    required: false
+    default: ""
+  date-format:
+    description: The date format to use
+    required: false
+    default: "%Y-%m-%d"
+
+runs:
+  using: composite
+  steps:
+    - name: Install toolchain
+      uses: dtolnay/rust-toolchain@nightly
+
+    - name: Install git-cliff
+      run: cargo install --path git-cliff/
+      shell: bash
+
+    - name: Set git config
+      run: |
+        git config --global user.name "github-actions[bot]"
+        git config --global user.email "github-actions[bot]@users.noreply.github.com"
+      shell: bash
+
+    - name: Create commits and tags
+      working-directory: ${{ inputs.fixtures-dir }}
+      run: |
+        git init
+        ./commit.sh
+      shell: bash
+
+    - name: Generate a changelog
+      working-directory: ${{ inputs.fixtures-dir }}
+      run: git cliff --config cliff.toml ${{ inputs.command }} > output.md
+      shell: bash
+
+    - name: Compare the output with the expected output
+      working-directory: ${{ inputs.fixtures-dir }}
+      env:
+        IN_DATE_FORMAT: ${{ inputs.date-format }}
+      run: |
+        cat output.md
+        current_date=$(date +"$IN_DATE_FORMAT")
+        sed -i "s/<<DATE>>/$current_date/g" expected.md
+        diff --strip-trailing-cr output.md expected.md
+      shell: bash
+
+    # test backwards compatibility using v1 confiuration
+
+    - name: Generate a chanlog using v1 configuration
+      if: ${{ hashFiles(format('{0}/cliff.v1.toml', inputs.fixtures-dir)) }}
+      working-directory: ${{ inputs.fixtures-dir }}
+      run: git-cliff --config cliff.v1.toml --config-version 1 ${{ inputs.command }} > output.md
+      shell: bash
+
+    - name: Compare the v1 configuration output with the expected output
+      if: ${{ hashFiles(format('{0}/cliff.v1.toml', inputs.fixtures-dir)) }}
+      working-directory: ${{ inputs.fixtures-dir }}
+      env:
+        IN_DATE_FORMAT: ${{ inputs.date-format }}
+      run: |
+        cat output.md
+        current_date=$(date +"$IN_DATE_FORMAT")
+        sed -i "s/<<DATE>>/$current_date/g" expected.md
+        diff --strip-trailing-cr output.md expected.md
+      shell: bash

.github/fixtures/new-fixture-template/cliff.toml

@@ -1,12 +1,11 @@
 [changelog]
-# changelog header
+# A static header for the changelog.
 header = """
 # Changelog\n
 All notable changes to this project will be documented in this file.\n
 """
-# template for the changelog body
-# https://keats.github.io/tera/docs/#introduction
-body = """
+# A Tera template to be rendered for each release in the changelog (see https://keats.github.io/tera/docs/#introduction).
+body_template = """
 {% if version %}\
     ## [{{ version | trim_start_matches(pat="v") }}] - {{ timestamp | date(format="%Y-%m-%d") }}
 {% else %}\
@@ -19,15 +18,16 @@ body = """
     {% endfor %}
 {% endfor %}\n
 """
-# template for the changelog footer
-footer = """
+# A Tera template to be rendered as the changelog's footer (see https://keats.github.io/tera/docs/#introduction).
+footer_template = """
 <!-- generated by git-cliff -->
 """
-# remove the leading and trailing whitespace from the templates
-trim = true
+# Whether to remove leading and trailing whitespaces from all lines of the changelog's body.
+trim_body_whitespace = true
 
-[git]
-# regex for parsing and grouping commits
+[commit]
+# A list of parsers using regex for extracting data from the commit message.
+# Sets the commits' `group` and `scope` and can decide to exclude commits from further processing.
 commit_parsers = [
     { message = "^feat", group = "Features", default_scope = "app" },
     { message = "^fix", group = "Bug Fixes", scope = "cli" },

.github/fixtures/test-bump-version-keep-zerover/cliff.toml

@@ -1,12 +1,11 @@
 [changelog]
-# changelog header
+# A static header for the changelog.
 header = """
 # Changelog\n
 All notable changes to this project will be documented in this file.\n
 """
-# template for the changelog body
-# https://keats.github.io/tera/docs/#introduction
-body = """
+# A Tera template to be rendered for each release in the changelog (see https://keats.github.io/tera/docs/#introduction).
+body_template = """
 {% if version %}\
     ## [{{ version | trim_start_matches(pat="v") }}]
 {% else %}\
@@ -19,12 +18,12 @@ body = """
     {% endfor %}
 {% endfor %}\n
 """
-# template for the changelog footer
-footer = """
+# A Tera template to be rendered as the changelog's footer (see https://keats.github.io/tera/docs/#introduction).
+footer_template = """
 <!-- generated by git-cliff -->
 """
-# remove the leading and trailing whitespace from the templates
-trim = true
+# Whether to remove leading and trailing whitespaces from all lines of the changelog's body.
+trim_body_whitespace = true
 
 [bump]
 features_always_bump_minor = false

.github/fixtures/test-bump-version/cliff.toml

@@ -1,12 +1,11 @@
 [changelog]
-# changelog header
+# A static header for the changelog.
 header = """
 # Changelog\n
 All notable changes to this project will be documented in this file.\n
 """
-# template for the changelog body
-# https://keats.github.io/tera/docs/#introduction
-body = """
+# A Tera template to be rendered for each release in the changelog (see https://keats.github.io/tera/docs/#introduction).
+body_template = """
 {% if version %}\
     ## [{{ version | trim_start_matches(pat="v") }}]
 {% else %}\
@@ -19,9 +18,9 @@ body = """
     {% endfor %}
 {% endfor %}\n
 """
-# template for the changelog footer
-footer = """
+# A Tera template to be rendered as the changelog's footer (see https://keats.github.io/tera/docs/#introduction).
+footer_template = """
 <!-- generated by git-cliff -->
 """
-# remove the leading and trailing whitespace from the templates
-trim = true
+# Whether to remove leading and trailing whitespaces from all lines of the changelog's body.
+trim_body_whitespace = true

.github/fixtures/test-topo-order-arg/cliff.toml → .github/fixtures/test-bump-version/cliff.v1.toml

@@ -8,7 +8,7 @@ All notable changes to this project will be documented in this file.\n
 # https://keats.github.io/tera/docs/#introduction
 body = """
 {% if version %}\
-    ## [{{ version | trim_start_matches(pat="v") }}] - {{ timestamp | date(format="%Y-%m-%d") }}
+    ## [{{ version | trim_start_matches(pat="v") }}]
 {% else %}\
     ## [unreleased]
 {% endif %}\

.github/fixtures/test-bumped-version/cliff.toml

@@ -1,12 +1,11 @@
 [changelog]
-# changelog header
+# A static header for the changelog.
 header = """
 # Changelog\n
 All notable changes to this project will be documented in this file.\n
 """
-# template for the changelog body
-# https://keats.github.io/tera/docs/#introduction
-body = """
+# A Tera template to be rendered for each release in the changelog (see https://keats.github.io/tera/docs/#introduction).
+body_template = """
 {% if version %}\
     ## [{{ version | trim_start_matches(pat="v") }}]
 {% else %}\
@@ -19,9 +18,9 @@ body = """
     {% endfor %}
 {% endfor %}\n
 """
-# template for the changelog footer
-footer = """
+# A Tera template to be rendered as the changelog's footer (see https://keats.github.io/tera/docs/#introduction).
+footer_template = """
 <!-- generated by git-cliff -->
 """
-# remove the leading and trailing whitespace from the templates
-trim = true
+# Whether to remove leading and trailing whitespaces from all lines of the changelog's body.
+trim_body_whitespace = true

.github/fixtures/test-commit-footers/cliff.toml

@@ -1,12 +1,11 @@
 [changelog]
-# changelog header
+# A static header for the changelog.
 header = """
 # Changelog\n
 All notable changes to this project will be documented in this file.\n
 """
-# template for the changelog body
-# https://keats.github.io/tera/docs/#introduction
-body = """
+# A Tera template to be rendered for each release in the changelog (see https://keats.github.io/tera/docs/#introduction).
+body_template = """
 {% if version %}\
     ## [{{ version | trim_start_matches(pat="v") }}] - {{ timestamp | date(format="%Y-%m-%d") }}
 {% else %}\
@@ -22,9 +21,9 @@ body = """
     {% endfor %}
 {% endfor %}\n
 """
-# template for the changelog footer
-footer = """
+# A Tera template to be rendered as the changelog's footer (see https://keats.github.io/tera/docs/#introduction).
+footer_template = """
 <!-- generated by git-cliff -->
 """
-# remove the leading and trailing whitespace from the templates
-trim = true
+# Whether to remove leading and trailing whitespaces from all lines of the changelog's body.
+trim_body_whitespace = true

.github/fixtures/test-commit-preprocessors/cliff.toml

@@ -1,12 +1,11 @@
 [changelog]
-# changelog header
+# A static header for the changelog.
 header = """
 # Changelog\n
 All notable changes to this project will be documented in this file.\n
 """
-# template for the changelog body
-# https://keats.github.io/tera/docs/#introduction
-body = """
+# A Tera template to be rendered for each release in the changelog (see https://keats.github.io/tera/docs/#introduction).
+body_template = """
 {% if version %}\
     ## [{{ version | trim_start_matches(pat="v") }}] - {{ timestamp | date(format="%Y-%m-%d") }}
 {% else %}\
@@ -19,16 +18,16 @@ body = """
     {% endfor %}
 {% endfor %}\n
 """
-# template for the changelog footer
-footer = """
+# A Tera template to be rendered as the changelog's footer (see https://keats.github.io/tera/docs/#introduction).
+footer_template = """
 <!-- generated by git-cliff -->
 """
-# remove the leading and trailing whitespace from the templates
-trim = true
+# Whether to remove leading and trailing whitespaces from all lines of the changelog's body.
+trim_body_whitespace = true
 
-[git]
-# regex for preprocessing the commit messages
-commit_preprocessors = [
+[commit]
+# A list of preprocessors to modify commit messages using regex prior to further processing.
+message_preprocessors = [
     { pattern = '\(#([0-9]+)\)', replace = "([issue#${1}](https://github.com/orhun/git-cliff/issues/${1}))" },
     { pattern = "  +", replace = " " },
 ]

.github/fixtures/test-configure-from-cargo-toml/Cargo.toml

@@ -4,14 +4,13 @@ version = "0.1.0"
 edition = "2021"
 
 [package.metadata.git-cliff.changelog]
-# changelog header
+# A static header for the changelog.
 header = """
 # Changelog\n
 All notable changes to this project will be documented in this file.\n
 """
-# template for the changelog body
-# https://keats.github.io/tera/docs/#introduction
-body = """
+# A Tera template to be rendered for each release in the changelog (see https://keats.github.io/tera/docs/#introduction).
+body_template = """
 {% if version %}\
     ## [{{ version | trim_start_matches(pat="v") }}] - {{ timestamp | date(format="%Y-%m-%d") }}
 {% else %}\
@@ -24,15 +23,16 @@ body = """
     {% endfor %}
 {% endfor %}\n
 """
-# template for the changelog footer
-footer = """
+# A Tera template to be rendered as the changelog's footer (see https://keats.github.io/tera/docs/#introduction).
+footer_template = """
 <!-- generated by git-cliff -->
 """
-# remove the leading and trailing whitespace from the templates
-trim = true
+# Whether to remove leading and trailing whitespaces from all lines of the changelog's body.
+trim_body_whitespace = true
 
-[package.metadata.git-cliff.git]
-# regex for parsing and grouping commits
+[package.metadata.git-cliff.commit]
+# A list of parsers using regex for extracting data from the commit message.
+# Sets the commits' `group` and `scope` and can decide to exclude commits from further processing.
 commit_parsers = [
     { message = "^feat", group = "Features", default_scope = "app" },
     { message = "^fix", group = "Bug Fixes", scope = "cli" },