From 98eac38d344ab971eb7e623e71f1f5b89e8015e0 Mon Sep 17 00:00:00 2001
From: "George L. Yermulnik" <yz@yz.kiev.ua>
Date: Fri, 5 Jul 2024 22:28:51 +0300
Subject: [PATCH] docs: Add `gh-changelog` config and `CHANGELOG.howto.md` +
 release changelog config (#472)

* docs: Add `gh-chagnelog` config and `CHANGELOG.howto.md` [skip ci]
* docs: Add `.github/release.yml` to make release changelogs more structured [skip ci]
---
 .changelog.yml      | 22 ++++++++++++++++++++++
 .github/release.yml | 28 ++++++++++++++++++++++++++++
 CHANGELOG.howto.md  | 36 ++++++++++++++++++++++++++++++++++++
 3 files changed, 86 insertions(+)
 create mode 100644 .changelog.yml
 create mode 100644 .github/release.yml
 create mode 100644 CHANGELOG.howto.md

diff --git a/.changelog.yml b/.changelog.yml
new file mode 100644
index 00000000..5a3d0c3c
--- /dev/null
+++ b/.changelog.yml
@@ -0,0 +1,22 @@
+---
+file_name: CHANGELOG.md.new
+excluded_labels:
+  - maintenance
+  - dependencies
+sections:
+  added:
+    - enhancement
+    - feature
+    - new feature
+  changed:
+    - backwards-incompatible
+    - depricated
+  fixed:
+    - bug
+    - bugfix
+    - fix
+    - fixed
+skip_entries_without_label: false
+show_unreleased: true
+check_for_updates: true
+logger: console
diff --git a/.github/release.yml b/.github/release.yml
new file mode 100644
index 00000000..b629aa08
--- /dev/null
+++ b/.github/release.yml
@@ -0,0 +1,28 @@
+# https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes
+changelog:
+  categories:
+    - title: Added
+      labels:
+        - enhancement
+        - feature
+        - new feature
+    - title: Changed
+      labels:
+        - backwards-incompatible
+        - depricated
+    - title: Fixed
+      labels:
+        - bug
+        - bugfix
+        - fix
+        - fixed
+    - title: Documentation
+      labels:
+        - docs
+        - documentation
+    - title: Dependencies
+      labels:
+        - dependencies
+    - title: Other
+      labels:
+        - "*"
diff --git a/CHANGELOG.howto.md b/CHANGELOG.howto.md
new file mode 100644
index 00000000..5aada13c
--- /dev/null
+++ b/CHANGELOG.howto.md
@@ -0,0 +1,36 @@
+# How to update CHANGELOG with info on latest release
+
+1. [Install GH CLI](https://github.com/cli/cli?tab=readme-ov-file#installation).
+   * [Configure it](https://cli.github.com/manual/#configuration)
+1. [Install `gh-changelog`](https://github.com/chelnak/gh-changelog?tab=readme-ov-file#installation-and-usage)
+   * Ensure the `.changelog.yml` file is in the root of the repo:
+     ```yaml
+     ---
+     file_name: CHANGELOG.md.new
+     excluded_labels:
+       - maintenance
+       - dependencies
+     sections:
+       added:
+         - enhancement
+         - feature
+         - new feature
+       changed:
+         - backwards-incompatible
+         - depricated
+       fixed:
+         - bug
+         - bugfix
+         - fix
+         - fixed
+     skip_entries_without_label: false
+     show_unreleased: true
+     check_for_updates: true
+     logger: console
+     ```
+1. Pull latest data from the `origin`
+1. Create new branch and name it accordingly (e.g. `docs/Update_CHANGELOG_with_<latest_version_tag>`).
+1. Run `gh changelog new --from-version <previous_version_tag> --next-version <latest_version_tag>` to generate CHANGELOG since the `<previous_version_tag>` to `<latest_version_tag>`.
+1. Open `CHANGELOG.md.new`, re-arrange log entries to improve readability if applicable and copy everything under the `The format is based on […]` line (release version(s) with description of changes).
+1. Open [`CHANGELOG.md`](CHANGELOG.md) and paste copied data right under `The format is based on […]` line (keep empty line between this line and pasted data).
+1. Push your changes using conventional commit messages like ``docs: Update CHANGELOG with `<latest_version_tag>` ``, create PR and have someone from [CODEOWNERS](.github/CODEOWNERS) review and approve it.