feat(changelog): make changelog.header a template

Made changelog.header into a template like changelog.body and changelog.footer.
Added test test-header-template.

.github/fixtures/test-header-template/cliff.toml

@@ -0,0 +1,31 @@
+[changelog]
+# changelog header
+header = """
+# Changelog\n
+{% for release in releases %}\
+    {% if release.version %}\
+        {% if release.previous.version %}\
+            <!--{{ release.previous.version }}..{{ release.version }}-->
+        {% endif %}\
+    {% else %}\
+        <!--{{ release.previous.version }}..HEAD-->
+    {% endif %}\
+{% endfor %}\
+"""
+# template for the changelog body
+# https://keats.github.io/tera/docs/#introduction
+body = """
+{% if version %}\
+    ## [{{ version | trim_start_matches(pat="v") }}]
+{% else %}\
+    ## [unreleased]
+{% endif %}\
+{% for group, commits in commits | group_by(attribute="group") %}
+    ### {{ group | upper_first }}
+    {% for commit in commits %}
+        - {% if commit.breaking %}[**breaking**] {% endif %}{{ commit.message | upper_first }}\
+    {% endfor %}
+{% endfor %}\n
+"""
+# remove the leading and trailing whitespace from the templates
+trim = true

.github/fixtures/test-header-template/commit.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+set -e
+
+GIT_COMMITTER_DATE="2021-01-23 01:23:45" git commit --allow-empty -m "feat: add feature 1"
+GIT_COMMITTER_DATE="2021-01-23 01:23:45" git commit --allow-empty -m "feat: add feature 2"
+git tag v0.1.0
+
+GIT_COMMITTER_DATE="2021-01-23 01:23:46" git commit --allow-empty -m "fix: fix feature 1"
+GIT_COMMITTER_DATE="2021-01-23 01:23:46" git commit --allow-empty -m "fix: fix feature 2"
+git tag v0.2.0
+
+GIT_COMMITTER_DATE="2021-01-23 01:23:47" git commit --allow-empty -m "feat: add footer"
+git tag v3.0.0
+
+GIT_COMMITTER_DATE="2021-01-23 01:23:47" git commit --allow-empty -m "test: footer"
+GIT_COMMITTER_DATE="2021-01-23 01:23:47" git commit --allow-empty -m "perf: footer"

.github/fixtures/test-header-template/expected.md

@@ -0,0 +1,36 @@
+# Changelog
+<!--v3.0.0..HEAD-->
+<!--v0.2.0..v3.0.0-->
+<!--v0.1.0..v0.2.0-->
+
+All notable changes to this project will be documented in this file.
+
+## [unreleased]
+
+### Perf
+
+- Footer
+
+### Test
+
+- Footer
+
+## [3.0.0]
+
+### Feat
+
+- Add footer
+
+## [0.2.0]
+
+### Fix
+
+- Fix feature 1
+- Fix feature 2
+
+## [0.1.0]
+
+### Feat
+
+- Add feature 1
+- Add feature 2

.github/workflows/test-fixtures.yml

@@ -37,6 +37,7 @@ jobs:
             command: --bump
           - fixtures-name: test-bumped-version
             command: --bumped-version
+          - fixtures-name: test-header-template
           - fixtures-name: test-footer-template
           - fixtures-name: test-keep-a-changelog-links
           - fixtures-name: test-keep-a-changelog-links-current-arg

git-cliff-core/src/changelog.rs

@@ -27,6 +27,7 @@ use std::time::{
 pub struct Changelog<'a> {
 	/// Releases that the changelog will contain.
 	pub releases:       Vec<Release<'a>>,
+	header_template:    Option<Template>,
 	body_template:      Template,
 	footer_template:    Option<Template>,
 	config:             &'a Config,
@@ -39,6 +40,10 @@ impl<'a> Changelog<'a> {
 		let trim = config.changelog.trim.unwrap_or(true);
 		let mut changelog = Self {
 			releases,
+			header_template: match &config.changelog.header {
+				Some(header) => Some(Template::new(header.to_string(), false)?),
+				None => None,
+			},
 			body_template: Template::new(
 				config
 					.changelog
@@ -409,14 +414,8 @@ impl<'a> Changelog<'a> {
 			.postprocessors
 			.clone()
 			.unwrap_or_default();
-		if let Some(header) = &self.config.changelog.header {
-			let write_result = write!(out, "{header}");
-			if let Err(e) = write_result {
-				if e.kind() != std::io::ErrorKind::BrokenPipe {
-					return Err(e.into());
-				}
-			}
-		}
+
+		// fetch release metadata from remote repositories
 		let mut releases = self.releases.clone();
 		for release in releases.iter_mut() {
 			#[cfg(feature = "github")]
@@ -434,6 +433,30 @@ impl<'a> Changelog<'a> {
 				bitbucket_commits.clone(),
 				bitbucket_pull_request.clone(),
 			)?;
+		}
+
+		// render the header_template
+		if let Some(header_template) = &self.header_template {
+			let write_result = writeln!(
+				out,
+				"{}",
+				header_template.render(
+					&Releases {
+						releases: &releases,
+					},
+					Some(&additional_context),
+					&postprocessors,
+				)?
+			);
+			if let Err(e) = write_result {
+				if e.kind() != std::io::ErrorKind::BrokenPipe {
+					return Err(e.into());
+				}
+			}
+		}
+
+		// render the body_template for each release
+		for release in releases.iter_mut() {
 			let write_result = write!(
 				out,
 				"{}",
@@ -449,6 +472,8 @@ impl<'a> Changelog<'a> {
 				}
 			}
 		}
+
+		// render the footer_template
 		if let Some(footer_template) = &self.footer_template {
 			let write_result = writeln!(
 				out,
@@ -467,6 +492,7 @@ impl<'a> Changelog<'a> {
 				}
 			}
 		}
+
 		Ok(())
 	}
 
@@ -836,6 +862,7 @@ mod test {
 		assert_eq!(
 			String::from(
 				r#"# Changelog
+
 			## Release [v1.1.0] - 1970-01-01
 
 
@@ -941,6 +968,7 @@ chore(deps): fix broken deps
 		assert_eq!(
 			String::from(
 				r#"# Changelog
+
 			## Unreleased
 
 			### Bug Fixes
@@ -1044,6 +1072,7 @@ chore(deps): fix broken deps
 		changelog.generate(&mut out)?;
 		expect_test::expect![[r#"
     # Changelog
+		
     ## Unreleased
 
     ### Bug Fixes