From 519a2b1d1a80a1731caac2956ffd0aa7ea737a02 Mon Sep 17 00:00:00 2001
From: Kristoffer Dalby <kristoffer@dalby.cc>
Date: Wed, 29 Apr 2026 13:50:11 +0000
Subject: [PATCH] docs: require issue references in commit messages

Promote the optional Fixes #N hint in the PR template to a non-
optional checklist item. Add a Commit messages section to
CONTRIBUTING.md listing the accepted verbs and skip tokens.
skip-issuebot
---
 .github/pull_request_template.md |  3 +--
 CONTRIBUTING.md                  | 24 ++++++++++++++++++++++++
 2 files changed, 25 insertions(+), 2 deletions(-)

diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index 9d8e731d6..f43da0954 100644
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -18,5 +18,4 @@ If you find mistakes in the documentation, please submit a fix to the documentat
 - [ ] added integration tests
 - [ ] updated documentation if needed
 - [ ] updated CHANGELOG.md
-
-<!-- If applicable, please reference the issue using `Fixes #XXX` and add tests to cover your new code. -->
+- [ ] referenced an issue in every commit message (e.g. `Fixes #N` or `Updates #N`) — see [CONTRIBUTING.md](./CONTRIBUTING.md#commit-messages)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 4c3ca1300..287140b1a 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -32,3 +32,27 @@ Headscale is open to code contributions for bug fixes without discussion.
 ## Documentation
 
 If you find mistakes in the documentation, please submit a fix to the documentation.
+
+## Commit messages
+
+Every commit in a pull request must reference a GitHub issue. CI enforces this via `.github/scripts/commit-lint.nu`.
+
+Use one of the following at the start of a line in the commit body:
+
+- `Fixes #N` — closes issue N when the PR merges.
+- `Updates #N` — references issue N without closing it.
+
+Cross-repo references (`Updates juanfont/headscale#N`) and full GitHub issue URLs are accepted.
+
+The full set of accepted verbs (case-insensitive) is: `close`, `closes`, `closed`, `fix`, `fixes`, `fixed`, `resolve`, `resolves`, `resolved`, `updates`, `for`.
+
+### Skip tokens
+
+Some commits do not need an issue reference:
+
+- Authors containing `[bot]` (e.g. `dependabot[bot]`, `renovate[bot]`) are skipped.
+- Subjects starting with `Revert ` are skipped (the original commit carries the reference).
+- A line equal to `#cleanup` skips trivial cleanups.
+- The token `skip-issuebot` anywhere in the body skips a commit.
+
+This rule is modelled after [tailscale/issuebot](https://github.com/tailscale/issuebot).