From f3ed05c307a11ee838511a0b855277eb1c774a54 Mon Sep 17 00:00:00 2001
From: Ken Brewer <kenibrewer@users.noreply.github.com>
Date: Tue, 7 Nov 2023 14:28:49 +0000
Subject: [PATCH] docs(changelog): add commitizen template

This change adds a commitizen CHANGELOG template that includes a link to the detailed GitHub release notes.

Co-authored-by: Dave Bunten <dave.bunten@cuanschutz.edu>
---
 CONTRIBUTING.md                      | 10 ++++++----
 dev_tools/commitizen/CHANGELOG.md.j2 | 23 +++++++++++++++++++++++
 pyproject.toml                       |  1 +
 3 files changed, 30 insertions(+), 4 deletions(-)
 create mode 100644 dev_tools/commitizen/CHANGELOG.md.j2

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 92289299..e51262e8 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -175,10 +175,12 @@ Project maintainers are responsible for releasing new versions of pycytominer.
 Creating a new release includes the following steps:
 
 1. Create a new branch from `main` for the release (e.g. `release-v1.0.0`)
-2. Run the command `cz bump --files-only` to update the version number in `CITATION.cff` and `pyproject.toml:tool.commitizen`.
-3. Review the changes to CHANGELOG.md and edit as needed.
-4. Review the [commit history](https://github.com/cytomining/pycytominer/compare) from the last release and add documentation for changes that weren't auto-included because they didn't follow the conventional-commit standard.
-5. `git add` all changes and run `cz bump` to create the release commit.
+2. Review the [commit history](https://github.com/cytomining/pycytominer/compare) from the last release and check whether it includes commits that don't follow the [conventional commit standard](https://www.conventionalcommits.org/en/v1.0.0/#summary).
+   If all changes follow conventional commits, skip to step 5.
+3. Run the command `cz bump --files-only` to update the version number in `CITATION.cff` and `pyproject.toml:tool.commitizen` and generate the draft changelog.
+4. Review the changes to `CHANGELOG.md`. If necessary, add descriptions of missing changes and modify descriptions to match conventional commits standard.
+5. `git add` any manual changes and run `cz bump` to create the release commit.
+   Push the changes to the release branch.
 6. Create a pull request for the release branch into `main`.
 7. Request a review from another maintainer.
 8. Once the pull request is approved, merge it into `main`.
diff --git a/dev_tools/commitizen/CHANGELOG.md.j2 b/dev_tools/commitizen/CHANGELOG.md.j2
new file mode 100644
index 00000000..eb4f83a3
--- /dev/null
+++ b/dev_tools/commitizen/CHANGELOG.md.j2
@@ -0,0 +1,23 @@
+{# Adapted from https://github.com/commitizen-tools/commitizen/blob/1d842b5d823a452109070f8af8857249e95f7713/commitizen/templates/CHANGELOG.md.j2 #}
+{% for entry in tree %}
+
+## {{ entry.version }}{% if entry.date %} ({{ entry.date }}){% endif %}
+
+{# Add link to the detailed GitHub release notes #}
+[Detailed Release Notes](https://github.com/cytomining/pycytominer/releases/tag/{{ entry.version }})
+
+{% for change_key, changes in entry.changes.items() %}
+
+{% if change_key %}
+### {{ change_key }}
+{% endif %}
+
+{% for change in changes %}
+{% if change.scope %}
+- **{{ change.scope }}**: {{ change.message }}
+{% elif change.message %}
+- {{ change.message }}
+{% endif %}
+{% endfor %}
+{% endfor %}
+{% endfor %}
diff --git a/pyproject.toml b/pyproject.toml
index d5b70ab3..de9e5801 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -103,6 +103,7 @@ tag_format = "v$version"
 version_scheme = "pep440"
 version_provider = "commitizen"
 update_changelog_on_bump = true
+template = "dev_tools/commitizen/CHANGELOG.md.j2"
 version_files = [
     "CITATION.cff"
 ]