From 1342a76e60ff46c45dcceee689f6eed180eb0650 Mon Sep 17 00:00:00 2001
From: Ogulcan Celik <ogulcancelik@gmail.com>
Date: Sat, 16 May 2026 23:52:15 +0300
Subject: [PATCH] docs: document issue reference commits

---
 CONTRIBUTING.md | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 45aeae8b..31f0ba02 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -83,6 +83,20 @@ just ci
 
 Do not open a PR that bypasses failing tests, formatting, or build errors.
 
+## Issue references in commits
+
+If your PR relates to a GitHub issue, reference it in the commit body with `refs #<issue-number>`.
+
+Example:
+
+```text
+fix: handle pane focus
+
+refs #128
+```
+
+Do not use GitHub closing keywords like `fixes #128`, `closes #128`, or `resolves #128` in normal PR commits. Herdr closes released issues after a release is published, not when unreleased commits land on `master`.
+
 ## PR scope
 
 Small bug fixes that clearly match the existing design are good candidates for PRs after approval.