summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--.github/workflows/require-changelog-for-PRs.yml2
-rw-r--r--CONTRIBUTING.md35
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