feat(changelog): add 'template' option to supply a custom changelog template

commitizen/changelog.py

@@ -161,11 +161,19 @@ def order_changelog_tree(tree: Iterable, change_type_order: List[str]) -> Iterab
     return sorted_tree
 
 
-def render_changelog(tree: Iterable) -> str:
-    loader = PackageLoader("commitizen", "templates")
-    env = Environment(loader=loader, trim_blocks=True)
-    jinja_template = env.get_template("keep_a_changelog_template.j2")
-    changelog: str = jinja_template.render(tree=tree)
+def render_changelog(releases: Iterable, template: str = None) -> str:
+    env = Environment(trim_blocks=True)
+    jinja_template = None
+    if template:
+        # load template from given path
+        with open(template, "r") as f:
+            template_content = f.read()
+        jinja_template = env.from_string(template_content)
+    else:
+        # load default template from package
+        env.loader = PackageLoader("commitizen", "templates")
+        jinja_template = env.get_template("keep_a_changelog_template.j2")
+    changelog: str = jinja_template.render(releases=releases)
     return changelog
 
 

commitizen/cli.py

@@ -167,6 +167,7 @@
                         "name": "--file-name",
                         "help": "file name of changelog (default: 'CHANGELOG.md')",
                     },
+                    {"name": "--template", "help": "custom template to be used",},
                     {
                         "name": "--unreleased-version",
                         "help": (

commitizen/commands/bump.py

@@ -46,6 +46,9 @@ def __init__(self, config: BaseConfig, arguments: dict):
         self.changelog = arguments["changelog"] or self.config.settings.get(
             "update_changelog_on_bump"
         )
+        self.changelog_incremental = self.config.settings.get(
+            "changelog_incremental", False
+        )
         self.changelog_to_stdout = arguments["changelog_to_stdout"]
         self.no_verify = arguments["no_verify"]
         self.check_consistency = arguments["check_consistency"]
@@ -189,7 +192,7 @@ def __call__(self):  # noqa: C901
                     self.config,
                     {
                         "unreleased_version": new_tag_version,
-                        "incremental": True,
+                        "incremental": self.changelog_incremental,
                         "dry_run": True,
                     },
                 )
@@ -201,7 +204,7 @@ def __call__(self):  # noqa: C901
                 self.config,
                 {
                     "unreleased_version": new_tag_version,
-                    "incremental": True,
+                    "incremental": self.changelog_incremental,
                     "dry_run": dry_run,
                 },
             )

commitizen/commands/changelog.py

@@ -35,6 +35,9 @@ def __init__(self, config: BaseConfig, args):
         self.file_name = args.get("file_name") or self.config.settings.get(
             "changelog_file"
         )
+        self.template = args.get("template") or self.config.settings.get(
+            "changelog_template"
+        )
         self.incremental = args["incremental"] or self.config.settings.get(
             "changelog_incremental"
         )
@@ -114,7 +117,7 @@ def __call__(self):
         )
         if self.change_type_order:
             tree = changelog.order_changelog_tree(tree, self.change_type_order)
-        changelog_out = changelog.render_changelog(tree)
+        changelog_out = changelog.render_changelog(tree, self.template)
         changelog_out = changelog_out.lstrip("\n")
 
         if self.dry_run:

commitizen/templates/keep_a_changelog_template.j2

@@ -1,8 +1,8 @@
-{% for entry in tree %}
+{% for release in releases %}
 
-## {{ entry.version }}{% if entry.date %} ({{ entry.date }}){% endif %}
+## {{ release.version }}{% if release.date %} ({{ release.date }}){% endif %}
 
-{% for change_key, changes in entry.changes.items() %}
+{% for change_key, changes in release.changes.items() %}
 
 {% if change_key %}
 ### {{ change_key }}

docs/changelog.md

@@ -7,6 +7,7 @@ This command will generate a changelog following the committing rules establishe
 ```bash
 $ cz changelog --help
 usage: cz changelog [-h] [--dry-run] [--file-name FILE_NAME]
+                    [--template TEMPLATE]
                     [--unreleased-version UNRELEASED_VERSION] [--incremental]
                     [--start-rev START_REV]
 
@@ -15,6 +16,7 @@ optional arguments:
   --dry-run             show changelog to stdout
   --file-name FILE_NAME
                         file name of changelog (default: 'CHANGELOG.md')
+  --template TEMPLATE   custom template to be used
   --unreleased-version UNRELEASED_VERSION
                         set the value for the new version (use the tag value),
                         instead of using unreleased
@@ -112,6 +114,16 @@ Specify the name of the output file, remember that changelog only works with mar
 cz changelog --file-name="CHANGES.md"
 ```
 
+### `template`
+
+This value can be set in the `toml` file with the key `changelog_template` under `tools.commitizen`
+
+Specify a custom Jinja template to be used for the changelogs. Use the provided [default template](../commitizen/templates/keep_a_changelog_template.j2) as a reference for creating your own template.
+
+```bash
+cz changelog --template="CHANGELOG.md.j2"
+```
+
 ### `incremental`
 
 This flag can be set in the `toml` file with the key `changelog_incremental` under `tools.commitizen`

tests/test_changelog.py

@@ -848,6 +848,14 @@ def test_render_changelog(gitcommits, tags, changelog_content):
     )
     result = changelog.render_changelog(tree)
     assert result == changelog_content
+    # test with 'custom' template
+    tree = changelog.generate_tree_from_commits(
+        gitcommits, tags, parser, changelog_pattern
+    )
+    result = changelog.render_changelog(
+        tree, "commitizen/templates/keep_a_changelog_template.j2"
+    )
+    assert result == changelog_content
 
 
 def test_render_changelog_unreleased(gitcommits):