From 487bed2d953424fd30dd125082a3bf26600aa180 Mon Sep 17 00:00:00 2001
From: einfachIrgendwer0815
 <85333734+einfachIrgendwer0815@users.noreply.github.com>
Date: Sat, 24 Feb 2024 23:58:20 +0100
Subject: [PATCH] Change CONTRIBUTING.md according to new changelog
 requirements (#2839)

* Mention changelog requirements in CONTRIBUTING

* Refer to CONTRIBUTING in changelog workflow

* Clarify when changelog entries are necessary

---------

Co-authored-by: Martin Nordholts <martin.nordholts@codetale.se>
---
 .../workflows/require-changelog-for-PRs.yml   |  2 +-
 CONTRIBUTING.md                               | 35 +++++++++++++++----
 2 files changed, 29 insertions(+), 8 deletions(-)

diff --git a/.github/workflows/require-changelog-for-PRs.yml b/.github/workflows/require-changelog-for-PRs.yml
index 263fee22..9b9d7cde 100644
--- a/.github/workflows/require-changelog-for-PRs.yml
+++ b/.github/workflows/require-changelog-for-PRs.yml
@@ -29,5 +29,5 @@ jobs:
           ADDED=$(git diff -U0 "origin/${PR_BASE}" HEAD -- CHANGELOG.md | grep -P '^\+[^\+].+$')
           echo "Added lines in CHANGELOG.md:"
           echo "$ADDED"
-          echo "Grepping for PR info:"
+          echo "Grepping for PR info (see CONTRIBUTING.md):"
           grep "#${PR_NUMBER}\\b.*@${PR_SUBMITTER}\\b" <<< "$ADDED"
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index fe38e2f3..2b381b38 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -6,21 +6,42 @@ Thank you for considering to contribute to `bat`!
 
 ## Add an entry to the changelog
 
-If your contribution changes the behavior of `bat` (as opposed to a typo-fix
-in the documentation), please update the [`CHANGELOG.md`](CHANGELOG.md) file
-and describe your changes. This makes the release process much easier and
-therefore helps to get your changes into a new `bat` release faster.
+Keeping the [`CHANGELOG.md`](CHANGELOG.md) file up-to-date makes the release
+process much easier and therefore helps to get your changes into a new `bat`
+release faster. However, not every change to the repository requires a
+changelog entry. Below are a few examples of that.
+
+Please update the changelog if your contribution contains changes regarding
+any of the following:
+  - the behavior of `bat`
+  - syntax mappings
+  - syntax definitions
+  - themes
+  - the build system, linting, or CI workflows
+
+A changelog entry is not necessary when:
+  - updating documentation
+  - fixing typos
+
+>[!NOTE]
+> For PRs, a CI workflow verifies that a suitable changelog entry is
+> added. If such an entry is missing, the workflow will fail. If your
+> changes do not need an entry to the changelog (see above), that
+> workflow failure can be disregarded.
+
+
+### Changelog entry format
 
 The top of the `CHANGELOG` contains a *"unreleased"* section with a few
 subsections (Features, Bugfixes, …). Please add your entry to the subsection
 that best describes your change.
 
-Entries follow this format:
+Entries must follow this format:
 ```
 - Short description of what has been changed, see #123 (@user)
 ```
-Here, `#123` is the number of the original issue and/or your pull request.
-Please replace `@user` by your GitHub username.
+Please replace `#123` with the number of your pull request (not issue) and
+`@user` by your GitHub username.
 
 
 ## Development