🔧 misc(release): update CHANGELOG format

Note: needs git-cliff > 1.4.0 - Only show commit hash if there's no PR - Use new `remote` options for git-cliff - List authors and co-authors per commit - Add new contributors list per release
welpo · Feb 19, 2024 · be1f7b1 · be1f7b1
1 parent ff0be35
commit be1f7b1
Show file tree

Hide file tree

Showing 4 changed files with 73 additions and 98 deletions.
diff --git a/.github/workflows/cd.yml b/.github/workflows/cd.yml
@@ -50,7 +50,8 @@ jobs:
             --title "Release ${{ github.ref_name }}" \
             --notes "$(git-cliff --latest --strip all)"
         env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}  # For git-cliff
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}  # For `gh`
 
       # Update doteki-action.
       - name: Clone doteki-action

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -8,72 +8,72 @@ We use Semantic Versioning (SemVer) for our version numbers, formatted as MAJOR.
 
 ### 🐛 Bug fixes
 
-- *(cli)* Use a temp file for safe README updates - ([5d3ffa0](https://github.com/welpo/doteki/commit/5d3ffa0808f8b4e0af54226598d42d44f4086371))
+- *(cli)* Use a temp file for safe README updates ([5d3ffa0](https://github.com/welpo/doteki/commit/5d3ffa0808f8b4e0af54226598d42d44f4086371)) by [@welpo](https://github.com/welpo)
 
 ### 📝 Documentation
 
-- *(README)* Add git-sumi badge - ([31d1d78](https://github.com/welpo/doteki/commit/31d1d7885c3af77f5c34b6b40830c4093466f1c7))
-- *(README)* Add IPA notation for pronunciation - ([41a6438](https://github.com/welpo/doteki/commit/41a643813381c9c01953a5c3c30a6d87d3e30dd8))
-- *(website)* Turn githooks suggestion into a "tip" - ([7757145](https://github.com/welpo/doteki/commit/77571455f2a646e4de25300f8cd180c8202bce3e))
+- *(README)* Add git-sumi badge ([31d1d78](https://github.com/welpo/doteki/commit/31d1d7885c3af77f5c34b6b40830c4093466f1c7)) by [@welpo](https://github.com/welpo)
+- *(README)* Add IPA notation for pronunciation ([41a6438](https://github.com/welpo/doteki/commit/41a643813381c9c01953a5c3c30a6d87d3e30dd8)) by [@welpo](https://github.com/welpo)
+- *(website)* Turn githooks suggestion into a "tip" ([7757145](https://github.com/welpo/doteki/commit/77571455f2a646e4de25300f8cd180c8202bce3e)) by [@welpo](https://github.com/welpo)
 
 ### ♻️ Refactor
 
-- *(cli)* Avoid redundant file read for credits - ([748545e](https://github.com/welpo/doteki/commit/748545e32ad6e576c4d34d5f304cf0bf8ceb939e))
+- *(cli)* Avoid redundant file read for credits ([748545e](https://github.com/welpo/doteki/commit/748545e32ad6e576c4d34d5f304cf0bf8ceb939e)) by [@welpo](https://github.com/welpo)
 
 ### 🔧 Miscellaneous tasks
 
-- *(CD)* Bump dōteki in doteki-action on release - ([8e42cf1](https://github.com/welpo/doteki/commit/8e42cf11bbe48f25e45b76048e1931be0639e854))
-- *(CHANGELOG)* Update commit types - ([bb1ed55](https://github.com/welpo/doteki/commit/bb1ed554ca3f0595f3950766ce00596931898ad3))
-- *(CHANGELOG)* Improve emoji pattern - ([e2e84bf](https://github.com/welpo/doteki/commit/e2e84bfda1c19dec3cd18f7eb016c9f2b8d17979))
-- *(CI)* Update git-sumi config - ([19c824a](https://github.com/welpo/doteki/commit/19c824a906b006fa9173af24099a6b1d9b4ca9dd))
-- *(git-sumi)* Require a space after the gitmoji - ([c839160](https://github.com/welpo/doteki/commit/c839160bc5561412de079d7f333b61f1a605a67e))
-- *(release)* Verify version tag format on release - ([a95ab3f](https://github.com/welpo/doteki/commit/a95ab3ff41ef2d604c5bbf6dd3f67561fb98a889))
-- *(release)* Automate PyPI release - ([d1dbecb](https://github.com/welpo/doteki/commit/d1dbecb76e1422fd0633d21ab83de9ebe822293b))
+- *(CD)* Bump dōteki in doteki-action on release ([8e42cf1](https://github.com/welpo/doteki/commit/8e42cf11bbe48f25e45b76048e1931be0639e854)) by [@welpo](https://github.com/welpo)
+- *(CHANGELOG)* Update commit types ([bb1ed55](https://github.com/welpo/doteki/commit/bb1ed554ca3f0595f3950766ce00596931898ad3)) by [@welpo](https://github.com/welpo)
+- *(CHANGELOG)* Improve emoji pattern ([e2e84bf](https://github.com/welpo/doteki/commit/e2e84bfda1c19dec3cd18f7eb016c9f2b8d17979)) by [@welpo](https://github.com/welpo)
+- *(CI)* Update git-sumi config ([19c824a](https://github.com/welpo/doteki/commit/19c824a906b006fa9173af24099a6b1d9b4ca9dd)) by [@welpo](https://github.com/welpo)
+- *(git-sumi)* Require a space after the gitmoji ([c839160](https://github.com/welpo/doteki/commit/c839160bc5561412de079d7f333b61f1a605a67e)) by [@welpo](https://github.com/welpo)
+- *(release)* Verify version tag format on release ([a95ab3f](https://github.com/welpo/doteki/commit/a95ab3ff41ef2d604c5bbf6dd3f67561fb98a889)) by [@welpo](https://github.com/welpo)
+- *(release)* Automate PyPI release ([d1dbecb](https://github.com/welpo/doteki/commit/d1dbecb76e1422fd0633d21ab83de9ebe822293b)) by [@welpo](https://github.com/welpo)
 
 ## [0.0.3](https://github.com/welpo/doteki/compare/v0.0.2..v0.0.3) - 2024-02-06
 
 ### ✨ Features
 
-- Add -v | --version argument - ([941c2fd](https://github.com/welpo/doteki/commit/941c2fd7057792cdca5a6d088bb720b8b523d179))
+- Add -v | --version argument ([941c2fd](https://github.com/welpo/doteki/commit/941c2fd7057792cdca5a6d088bb720b8b523d179)) by [@welpo](https://github.com/welpo)
 
 ### 🐛 Bug fixes
 
-- *(test_cli)* Read/write using UTF-8 encoding - ([24c4756](https://github.com/welpo/doteki/commit/24c4756f6f388550627f2909af6caea3e762b68b))
-- Specify UTF-8 encoding when reading files - ([1ae728c](https://github.com/welpo/doteki/commit/1ae728c38920cb5d205306133a20b1893ba60c56))
+- *(test_cli)* Read/write using UTF-8 encoding ([24c4756](https://github.com/welpo/doteki/commit/24c4756f6f388550627f2909af6caea3e762b68b)) by [@welpo](https://github.com/welpo)
+- Specify UTF-8 encoding when reading files ([1ae728c](https://github.com/welpo/doteki/commit/1ae728c38920cb5d205306133a20b1893ba60c56)) by [@welpo](https://github.com/welpo)
 
 ### 📝 Documentation
 
-- *(contributing)* Enrich PR information - ([917bf4d](https://github.com/welpo/doteki/commit/917bf4d559d5515978aa4734aaad30f97c3e71bc))
-- *(plugin-standard)* Add link to developer guide - ([f7310ee](https://github.com/welpo/doteki/commit/f7310ee7e7985ea39868d08a6e8614fc213082da))
+- *(contributing)* Enrich PR information ([917bf4d](https://github.com/welpo/doteki/commit/917bf4d559d5515978aa4734aaad30f97c3e71bc)) by [@welpo](https://github.com/welpo)
+- *(plugin-standard)* Add link to developer guide ([f7310ee](https://github.com/welpo/doteki/commit/f7310ee7e7985ea39868d08a6e8614fc213082da)) by [@welpo](https://github.com/welpo)
 
 ### ♻️ Refactor
 
-- *(cli)* Improve code readability - ([915f02e](https://github.com/welpo/doteki/commit/915f02ebd81d4dc152585251519ed8a55afeb287))
-- Move parse_arguments definition after its calling - ([4cbb4bd](https://github.com/welpo/doteki/commit/4cbb4bdd5e93efabbe6c274161d14fb5662124aa))
+- *(cli)* Improve code readability ([915f02e](https://github.com/welpo/doteki/commit/915f02ebd81d4dc152585251519ed8a55afeb287)) by [@welpo](https://github.com/welpo)
+- Move parse_arguments definition after its calling ([4cbb4bd](https://github.com/welpo/doteki/commit/4cbb4bdd5e93efabbe6c274161d14fb5662124aa)) by [@welpo](https://github.com/welpo)
 
 ### 🔧 Miscellaneous tasks
 
-- *(CI)* Fix links in tag description - ([c37d53c](https://github.com/welpo/doteki/commit/c37d53ca26edc75c365b4b90f8377ee43608d7af))
-- *(README)* Remove codecov logo from shield - ([af4b318](https://github.com/welpo/doteki/commit/af4b31801a8a8de2e654cea08027d31d5a744a5f))
-- Use git-sumi to lint commit messages - ([3e03678](https://github.com/welpo/doteki/commit/3e036786f98341191bfb7ff6c57e31e71753eb8a))
-- Add pre-commit script - ([58ef244](https://github.com/welpo/doteki/commit/58ef244d73236091ca6cf20e2aac462314aafbe6))
-- Sort imports with `isort` - ([dbd21a2](https://github.com/welpo/doteki/commit/dbd21a2ba65d5a552da7f86c503792e6511f130b))
-- Add continuous deployment workflow - ([9f01646](https://github.com/welpo/doteki/commit/9f01646c3de3f82005fa16a1e61de8fb428cb5ed))
+- *(CI)* Fix links in tag description ([c37d53c](https://github.com/welpo/doteki/commit/c37d53ca26edc75c365b4b90f8377ee43608d7af)) by [@welpo](https://github.com/welpo)
+- *(README)* Remove codecov logo from shield ([af4b318](https://github.com/welpo/doteki/commit/af4b31801a8a8de2e654cea08027d31d5a744a5f)) by [@welpo](https://github.com/welpo)
+- Use git-sumi to lint commit messages ([3e03678](https://github.com/welpo/doteki/commit/3e036786f98341191bfb7ff6c57e31e71753eb8a)) by [@welpo](https://github.com/welpo)
+- Add pre-commit script ([58ef244](https://github.com/welpo/doteki/commit/58ef244d73236091ca6cf20e2aac462314aafbe6)) by [@welpo](https://github.com/welpo)
+- Sort imports with `isort` ([dbd21a2](https://github.com/welpo/doteki/commit/dbd21a2ba65d5a552da7f86c503792e6511f130b)) by [@welpo](https://github.com/welpo)
+- Add continuous deployment workflow ([9f01646](https://github.com/welpo/doteki/commit/9f01646c3de3f82005fa16a1e61de8fb428cb5ed)) by [@welpo](https://github.com/welpo)
 
 ## [0.0.2](https://github.com/welpo/doteki/compare/v0.0.1..v0.0.2) - 2024-01-26
 
 ### 🐛 Bug fixes
 
-- Add utf-8 encoding to file write operations - ([17a8584](https://github.com/welpo/doteki/commit/17a8584822c1cedaa38f6897eefebca70d7f6039))
+- Add utf-8 encoding to file write operations ([17a8584](https://github.com/welpo/doteki/commit/17a8584822c1cedaa38f6897eefebca70d7f6039)) by [@welpo](https://github.com/welpo)
 
 ### ♻️ Refactor
 
-- *(cli)* Improve error message on missing deps - ([3367dfa](https://github.com/welpo/doteki/commit/3367dfac2ac17459d70968d727e9879f2cc52a19))
+- *(cli)* Improve error message on missing deps ([3367dfa](https://github.com/welpo/doteki/commit/3367dfac2ac17459d70968d727e9879f2cc52a19)) by [@welpo](https://github.com/welpo)
 
 ## 0.0.1 - 2024-01-19
 
 ### ✨ Features
 
-- Initial commit - ([9d80472](https://github.com/welpo/doteki/commit/9d8047210edecbd0a4db2ba478f2dffab102ab68))
+- Initial commit ([9d80472](https://github.com/welpo/doteki/commit/9d8047210edecbd0a4db2ba478f2dffab102ab68)) by [@welpo](https://github.com/welpo)
 
 <!-- generated by git-cliff -->
diff --git a/cliff.toml b/cliff.toml
@@ -5,6 +5,10 @@
 # Configuration options are organized into tables and keys.
 # See documentation for more information on available options.
 
+[remote.github]
+owner = "welpo"
+repo = "doteki"
+
 [changelog]
 # changelog header
 header = """
@@ -17,9 +21,12 @@ We use Semantic Versioning (SemVer) for our version numbers, formatted as MAJOR.
 # template for the changelog body
 # https://keats.github.io/tera/docs/#introduction
 body = """
+{%- macro remote_url() -%}
+  https://github.com/{{ remote.github.owner }}/{{ remote.github.repo }}
+{%- endmacro -%}
 {% if version %}\
     {% if previous.version %}\
-        ## [{{ version | trim_start_matches(pat="v") }}](<REPO>/compare/{{ previous.version }}..{{ version }}) - {{ timestamp | date(format="%Y-%m-%d") }}
+        ## [{{ version | trim_start_matches(pat="v") }}]({{ self::remote_url() }}/compare/{{ previous.version }}..{{ version }}) - {{ timestamp | date(format="%Y-%m-%d") }}
     {% else %}\
         ## {{ version | trim_start_matches(pat="v") }} - {{ timestamp | date(format="%Y-%m-%d") }}
     {% endif %}\
@@ -29,7 +36,14 @@ body = """
 
 {% macro commit(commit, in_breaking_section=false) -%}
     - {% if commit.scope %}*({{ commit.scope }})* {% endif %}{% if commit.breaking and not in_breaking_section %}[**‼️BREAKING‼️**] {% endif %}\
-        {{ commit.message | upper_first }} - ([{{ commit.id | truncate(length=7, end="") }}](<REPO>/commit/{{ commit.id }}))\
+        {{ commit.message | upper_first }}\
+        {% if not commit.github.pr_number %} ([{{ commit.id | truncate(length=7, end="") }}]({{ self::remote_url() }}/commit/{{ commit.id }})){%- endif -%}{% if commit.github.username %} by @{{ commit.github.username }} \
+        {%- set co_authors = commit.footers | filter(attribute="token", value="Co-authored-by") | map(attribute="value") -%}
+        {%- set number_of_co_authors = co_authors | length -%}
+        {%- for co_author in co_authors -%}
+            {%- if not loop.last %}, {% else %} and {% endif %}@{{ co_author | split(pat=" <") | first | trim }}
+        {%- endfor -%}
+        {%- endif -%}
 {% endmacro -%}
 
 {%- set breaking_header_shown = false -%}
@@ -59,7 +73,19 @@ body = """
             {{ self::commit(commit=commit) }}
         {% endif -%}
     {% endfor -%}
-{% endfor %}\n
+{% endfor %}
+
+{%- if github.contributors | filter(attribute="is_first_time", value=true) | length != 0 -%}
+  {% raw %}\n{% endraw %}### 👥 New contributors
+  {% raw -%}\n{% endraw -%}
+{% for contributor in github.contributors | filter(attribute="is_first_time", value=true) %}
+  🫶 @{{ contributor.username }} made their first contribution
+    {%- if contributor.pr_number %} in \
+      [#{{ contributor.pr_number }}]({{ self::remote_url() }}/pull/{{ contributor.pr_number }}) \
+    {%- endif %}
+{% endfor %}
+{%- endif %}
+{% raw -%}\n{% endraw -%}
 """
 
 # remove the leading and trailing whitespace from the template
@@ -70,7 +96,7 @@ footer = """
 """
 # postprocessors
 postprocessors = [
-    { pattern = '<REPO>', replace = "https://github.com/welpo/doteki" }, # replace repository URL
+    # { pattern = " @([a-zA-Z0-9](?:[a-zA-Z0-9]+-?)*[a-zA-Z0-9])", replace = " [@$1](https://github.com/$1)"}, # add link to GitHub usernames (done in release script instead)
 ]
 
 [git]

diff --git a/release b/release
@@ -15,8 +15,7 @@ fi
 if [ "$#" -eq 1 ]; then
     VERSION_TAG=$1
 else
-    # After git-cliff version 1.4.0 it should be possible to run `git cliff --bumped-version`.
-    suggested_version=$(git cliff --unreleased --bump --context | jq -r .[0].version)
+    suggested_version=$(git cliff --bumped-version)
     echo -n "No version tag provided. git-cliff suggests $suggested_version. Proceed? [Y/n] "
     read user_input
 
@@ -42,79 +41,28 @@ poetry --quiet version "${VERSION_TAG#v}"
 
 # Update CHANGELOG.
 git cliff --tag "$VERSION_TAG" -o CHANGELOG.md
+sed -i.bak -e 's/ @\([a-zA-Z0-9]\([-a-zA-Z0-9]*[a-zA-Z0-9]\)\?\)/ [@\1](https:\/\/github.com\/\1)/g' CHANGELOG.md && rm CHANGELOG.md.bak
+sed -E 's/@([a-zA-Z0-9_-]+)/[@\1](https:\/\/github.com\/\1)/g' CHANGELOG.md > CHANGELOG.tmp && mv CHANGELOG.tmp CHANGELOG.md
 
 # Add all changes and commit.
 git add -A
 git commit -m "🔖 chore(release): prepare for $VERSION_TAG"
 
-# Template for the tag description.
-export GIT_CLIFF_TEMPLATE="\
-    {%- set breaking_header_shown = false -%}
-    {% for commit in commits -%}
-        {%- if commit.breaking and not breaking_header_shown %}
-            💥 BREAKING CHANGES 💥
-            {% set_global breaking_header_shown = true -%}
-        {%- endif %}
-        {%- if commit.breaking %}
-            - {{ commit.message | upper_first -}}
-        {% endif -%}
-    {% endfor %}
-    {% for group, group_commits in commits | group_by(attribute=\"group\") %}
-        {{ group | striptags | trim | upper_first }}
-        {% for commit in group_commits %}
-            - {% if commit.breaking %}[‼️BREAKING‼️] {% endif %}{{ commit.message | upper_first }}
-        {%- endfor %}
-    {% endfor %}"
-
-# Cleaner template for the tag description.
-export GIT_CLIFF__CHANGELOG__BODY=$(cat <<'EOF'
-{% if version %}\
-    ## [{{ version | trim_start_matches(pat="v") }}] - {{ timestamp | date(format="%Y-%m-%d") }}
-{% else %}\
-    ## unreleased
-{% endif %}\
-
-{% macro commit(commit, in_breaking_section=false) -%}
-    - {% if commit.scope %}*({{ commit.scope }})* {% endif %}{% if commit.breaking and not in_breaking_section %}[**‼️BREAKING‼️**] {% endif %}\
-        {{ commit.message | upper_first }} - ({{ commit.id | truncate(length=7, end="") }})\
-{% endmacro -%}
-
-{%- set breaking_header_shown = false -%}
-{% for commit in commits -%}
-    {% if commit.breaking and not breaking_header_shown -%}
-        {% raw %}\n### 💥 BREAKING CHANGES 💥\n{% endraw %}
-        {% set_global breaking_header_shown = true %}
-    {%- endif -%}
-    {%- if commit.breaking -%}
-        {{ self::commit(commit=commit, in_breaking_section=true) -}}
-    {% endif -%}
-{%- endfor -%}
-{%- if breaking_header_shown == true -%}
-    {% raw %}\n{% endraw %}\
-{%- endif -%}
-
-{% for group, commits in commits | group_by(attribute="group") %}
-    ### {{ group | striptags | trim | upper_first }}
-    {% for commit in commits
-    | filter(attribute="scope")
-    | sort(attribute="scope") %}
-        {{ self::commit(commit=commit) }}
-    {%- endfor -%}
-    {% raw %}\n{% endraw %}\
-    {%- for commit in commits %}
-        {%- if not commit.scope -%}
-            {{ self::commit(commit=commit) }}
-        {% endif -%}
-    {% endfor -%}
-{% endfor %}\n
-EOF
-)
 
 # Generate the tag description.
 changelog=$(git cliff --tag "$VERSION_TAG" --unreleased --strip all)
 
-# Undo the pre_processing that adds PR links.
+# Clean up tag's changelog; tag descriptions don't support markdown.
+# Remove PR links.
 changelog=$(echo "$changelog" | sed -E 's/\[\#([0-9]+)\]\(https:\/\/github\.com\/welpo\/[^\/]+\/issues\/([0-9]+)\)/#\1/g')
+# Remove commit links.
+changelog=$(echo "$changelog" | sed -E 's/\[([0-9a-f]+)\]\(https:\/\/github\.com\/welpo\/[^\/]+\/commit\/([0-9a-f]+)\)/\1/g')
+# Remove scopes.
+changelog=$(echo "$changelog" | sed -E 's/\*\(([^)]+)\)\* //g')
+# Remove markdown headers.
+changelog=$(echo "$changelog" | sed -E 's/^#+ //g')
+# Remove version comparison lines.
+changelog=$(echo "$changelog" | sed '/https:\/\/github\.com\/.*\/compare\/.*/d')
 
 # Create a signed and annotated tag.
 git tag -s -a "$VERSION_TAG" -m "Release $VERSION_TAG" -m "$changelog"