feat(changelog): make changelog.header a template (#697)

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

@@ -0,0 +1,31 @@
+[changelog]
+# changelog header
+header = """
+# Changelog
+{% 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,33 @@
+# Changelog
+<!--v3.0.0..HEAD-->
+<!--v0.2.0..v3.0.0-->
+<!--v0.1.0..v0.2.0-->
+## [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

git-cliff-core/src/changelog.rs

@@ -29,6 +29,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,
@@ -41,6 +42,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(), trim)?),
+				None => None,
+			},
 			body_template: Template::new(
 				config
 					.changelog
@@ -420,16 +425,14 @@ impl<'a> Changelog<'a> {
 			serde_json::to_value(self.config.remote.clone())?,
 		);
 		#[cfg(feature = "github")]
-		let (github_commits, github_pull_requests) = if self.config.remote.github.is_set()
-		{
+		let (github_commits, github_pull_requests) = if self.config.remote.github.is_set() {
 			self.get_github_metadata()
 				.expect("Could not get github metadata")
 		} else {
 			(vec![], vec![])
 		};
 		#[cfg(feature = "gitlab")]
-		let (gitlab_commits, gitlab_merge_request) = if self.config.remote.gitlab.is_set()
-		{
+		let (gitlab_commits, gitlab_merge_request) = if self.config.remote.gitlab.is_set() {
 			self.get_gitlab_metadata()
 				.expect("Could not get gitlab metadata")
 		} else {
@@ -502,15 +505,30 @@ impl<'a> Changelog<'a> {
 			.postprocessors
 			.clone()
 			.unwrap_or_default();
-		if let Some(header) = &self.config.changelog.header {
-			let write_result = write!(out, "{header}");
+
+		let mut releases = self.releases.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(&self.additional_context),
+					&postprocessors,
+				)?
+			);
 			if let Err(e) = write_result {
 				if e.kind() != std::io::ErrorKind::BrokenPipe {
 					return Err(e.into());
 				}
 			}
 		}
-		let mut releases = self.releases.clone();
+
+		// render the body template
 		for release in releases.iter_mut() {
 			let write_result = write!(
 				out,
@@ -527,6 +545,8 @@ impl<'a> Changelog<'a> {
 				}
 			}
 		}
+
+		// render the footer template
 		if let Some(footer_template) = &self.footer_template {
 			let write_result = writeln!(
 				out,
@@ -545,6 +565,7 @@ impl<'a> Changelog<'a> {
 				}
 			}
 		}
+
 		Ok(())
 	}
 

website/docs/configuration/changelog.md

@@ -24,7 +24,7 @@ postprocessors = [{ pattern = "foo", replace = "bar"}]
 
 ### header
 
-Header text that will be added to the beginning of the changelog.
+Footer template that will be rendered and added to the beginning of the changelog.
 
 ### body