From aa4d406158a7cc16f80ae9c16fb0ce498aef19d1 Mon Sep 17 00:00:00 2001 From: Ray Walker Date: Sun, 4 Oct 2026 16:14:09 +1100 Subject: [PATCH 1/7] chore: keep internal references out of docs and commit messages --- .pre-commit-config.yaml | 23 +++++++++++++++++++++++ README.md | 9 ++++++++- 2 files changed, 31 insertions(+), 1 deletion(-) create mode 100644 .pre-commit-config.yaml diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 0000000..771dc11 --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,23 @@ +# Pre-commit hooks. Install once per clone: prek install (Python pre-commit works too). +default_install_hook_types: [pre-commit, commit-msg] + +repos: + # Keeps internal references (ticket ids, secret-store paths, internal hosts and process + # names) out of user-facing docs and commit messages. The patterns are generic on purpose: + # a list of specific internal names would itself disclose them. + # Scope rule: https://docs.cachekit.io/contributing/#what-belongs-in-these-docs + - repo: local + hooks: + - id: no-internal-references + name: No internal references in docs + language: pygrep + entry: 'LAB-[0-9]+|op://|\.ts\.net|\bk3s\b|dev\.cachekit\.io|\bStage [0-9]|\bAC-[0-9]|github\.com/cachekit(?![\w-])' + files: ^(packages/[^/]+/)?README[^/]*$|^docs/ + types: [text] + stages: [pre-commit] + - id: no-internal-references-commit-msg + name: No internal references in commit message + language: pygrep + # Same patterns, skipping git's "#" comment lines, which quote the branch name. + entry: '^(?!#).*?(?:LAB-[0-9]+|op://|\.ts\.net|\bk3s\b|dev\.cachekit\.io|\bStage [0-9]|\bAC-[0-9]|github\.com/cachekit(?![\w-]))' + stages: [commit-msg] diff --git a/README.md b/README.md index 4bab124..d657761 100644 --- a/README.md +++ b/README.md @@ -385,7 +385,7 @@ ByteStorage envelope vectors from both sets must decode to the exact payload bytes, while re-encode byte-identity is asserted against the set matching this crate's current writer encoding — msgpack `bin`, since the protocol 1.1 `serde_bytes` -writer flip (LAB-866; `checksum` deliberately stays array-of-ints per the +writer flip (`checksum` deliberately stays array-of-ints per the protocol's normative scope exclusion). Legacy envelopes remain readable forever. `tests/dual_decode.rs` proves both reader shapes accept both encodings, @@ -416,6 +416,13 @@ This crate requires **Rust 1.85** or later (Edition 2024). --- +## Contributing + +User-facing docs in this repository follow CacheKit's shared rule on what belongs in them: +[What belongs in these docs](https://docs.cachekit.io/contributing/#what-belongs-in-these-docs). +`prek install` (or `pre-commit install`) sets up hooks that reject internal references in README +files, `docs/` and commit messages. + ## License MIT License — see [LICENSE](LICENSE) for details. From cee01d1bd20487b9b2b3c18d4d3cdf5a955a8270 Mon Sep 17 00:00:00 2001 From: Ray Walker Date: Sun, 4 Oct 2026 16:29:16 +1100 Subject: [PATCH 2/7] chore: narrow the cluster pattern, skip merge subjects, cover crate READMEs --- .pre-commit-config.yaml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 771dc11..f645250 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -11,13 +11,13 @@ repos: - id: no-internal-references name: No internal references in docs language: pygrep - entry: 'LAB-[0-9]+|op://|\.ts\.net|\bk3s\b|dev\.cachekit\.io|\bStage [0-9]|\bAC-[0-9]|github\.com/cachekit(?![\w-])' - files: ^(packages/[^/]+/)?README[^/]*$|^docs/ + entry: 'LAB-[0-9]+|op://|\.ts\.net|(?i:k3s cluster)|dev\.cachekit\.io|\bStage [0-9]|\bAC-[0-9]|github\.com/cachekit(?![\w-])' + files: ^((packages|crates)/[^/]+/)?README[^/]*$|^docs/ types: [text] stages: [pre-commit] - id: no-internal-references-commit-msg name: No internal references in commit message language: pygrep - # Same patterns, skipping git's "#" comment lines, which quote the branch name. - entry: '^(?!#).*?(?:LAB-[0-9]+|op://|\.ts\.net|\bk3s\b|dev\.cachekit\.io|\bStage [0-9]|\bAC-[0-9]|github\.com/cachekit(?![\w-]))' + # Same patterns, skipping git's "#" comment lines and "Merge" subjects, which quote branch names. + entry: '^(?!#|Merge ).*?(?:LAB-[0-9]+|op://|\.ts\.net|(?i:k3s cluster)|dev\.cachekit\.io|\bStage [0-9]|\bAC-[0-9]|github\.com/cachekit(?![\w-]))' stages: [commit-msg] From 25348ed5e8f316d9a2bfbe0c4a1b2757af5a3db5 Mon Sep 17 00:00:00 2001 From: Ray Walker Date: Sun, 4 Oct 2026 17:03:54 +1100 Subject: [PATCH 3/7] chore: read commit messages only above the scissors line, widen the k3s pattern git runs the commit-msg hook on the raw message file. With `git commit -v` (or commit.verbose) that file carries the staged diff below the scissors line, so any ticket id in a changed line rejected the commit. The hook now reads the message as one block and stops at the scissors line. It also skips 'Revert "' subjects, which quote the reverted subject the same way merge subjects quote branch names. Reverting a commit whose subject carries an id, via `revert --no-commit` or a reword, no longer fails. Revert bodies are still checked. The k3s pattern now also catches node and host wording, a hyphen or repeated whitespace before the noun, still without matching bare k3s paths. --- .pre-commit-config.yaml | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index f645250..f1934d7 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -11,13 +11,16 @@ repos: - id: no-internal-references name: No internal references in docs language: pygrep - entry: 'LAB-[0-9]+|op://|\.ts\.net|(?i:k3s cluster)|dev\.cachekit\.io|\bStage [0-9]|\bAC-[0-9]|github\.com/cachekit(?![\w-])' + entry: 'LAB-[0-9]+|op://|\.ts\.net|(?i:\bk3s\b[\s-]*(?:cluster|node|host))|dev\.cachekit\.io|\bStage [0-9]|\bAC-[0-9]|github\.com/cachekit(?![\w-])' files: ^((packages|crates)/[^/]+/)?README[^/]*$|^docs/ types: [text] stages: [pre-commit] - id: no-internal-references-commit-msg name: No internal references in commit message language: pygrep - # Same patterns, skipping git's "#" comment lines and "Merge" subjects, which quote branch names. - entry: '^(?!#|Merge ).*?(?:LAB-[0-9]+|op://|\.ts\.net|(?i:k3s cluster)|dev\.cachekit\.io|\bStage [0-9]|\bAC-[0-9]|github\.com/cachekit(?![\w-]))' + # Same patterns. git hands this hook the raw message, so it reads only down to the scissors + # line (`git commit -v` puts the staged diff below it) and skips "#" comment lines plus + # "Merge" and 'Revert "' subjects, which quote branch names and earlier subjects. + entry: '\A(?:(?!# -{24} >8 -{24}$)[^\n]*\n)*?(?!#|Merge |Revert ")[^\n]*?(?:LAB-[0-9]+|op://|\.ts\.net|(?i:\bk3s\b[\s-]*(?:cluster|node|host))|dev\.cachekit\.io|\bStage [0-9]|\bAC-[0-9]|github\.com/cachekit(?![\w-]))' + args: [--multiline] stages: [commit-msg] From 8984ed9a797b97c05ac5dcf6d2195904af1bf6cd Mon Sep 17 00:00:00 2001 From: Ray Walker Date: Sun, 4 Oct 2026 17:06:37 +1100 Subject: [PATCH 4/7] chore: one commit-message check that ignores the verbose diff and git's own merge and revert subjects --- .pre-commit-config.yaml | 27 ++++++++++++++++++++------- 1 file changed, 20 insertions(+), 7 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index f1934d7..8e91ddf 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -11,16 +11,29 @@ repos: - id: no-internal-references name: No internal references in docs language: pygrep - entry: 'LAB-[0-9]+|op://|\.ts\.net|(?i:\bk3s\b[\s-]*(?:cluster|node|host))|dev\.cachekit\.io|\bStage [0-9]|\bAC-[0-9]|github\.com/cachekit(?![\w-])' + entry: '\b(?i:LAB)-[0-9]+|op://|\.ts\.net|(?i:\bk3s[\s-]+(?:cluster|node|host)s?\b)|dev\.cachekit\.io|\bStage [0-9]|\bAC-[0-9]|github\.com/cachekit(?![\w-])' files: ^((packages|crates)/[^/]+/)?README[^/]*$|^docs/ types: [text] stages: [pre-commit] - id: no-internal-references-commit-msg name: No internal references in commit message - language: pygrep - # Same patterns. git hands this hook the raw message, so it reads only down to the scissors - # line (`git commit -v` puts the staged diff below it) and skips "#" comment lines plus - # "Merge" and 'Revert "' subjects, which quote branch names and earlier subjects. - entry: '\A(?:(?!# -{24} >8 -{24}$)[^\n]*\n)*?(?!#|Merge |Revert ")[^\n]*?(?:LAB-[0-9]+|op://|\.ts\.net|(?i:\bk3s\b[\s-]*(?:cluster|node|host))|dev\.cachekit\.io|\bStage [0-9]|\bAC-[0-9]|github\.com/cachekit(?![\w-]))' - args: [--multiline] + # Same patterns. git hands this hook the raw message file: "#" comment lines, the diff + # below the `git commit -v` scissors line, and its own merge and revert subjects, which + # quote branch names and earlier subjects. Only the text the author wrote is checked. + language: python + entry: python -c + args: + - | + import re, sys + P = re.compile(r"\b(?i:LAB)-[0-9]+|op://|\.ts\.net|(?i:\bk3s[\s-]+(?:cluster|node|host)s?\b)|dev\.cachekit\.io|\bStage [0-9]|\bAC-[0-9]|github\.com/cachekit(?![\w-])") + GIT_SUBJECT = re.compile(r"Merge (?:branch|branches|remote-tracking branch|tag|commit) '[^']*'(?: and '[^']*')*(?: of \S+)?(?: into \S+)?|Revert \".*\"") + text = open(sys.argv[1], encoding="utf-8", errors="replace").read() + text = text.split("# ------------------------ >8 ------------------------")[0] + lines = [line for line in text.splitlines() if line.strip() and not line.startswith("#")] + if lines and GIT_SUBJECT.fullmatch(lines[0]): + lines = lines[1:] + bad = [line for line in lines if P.search(line)] + for line in bad: + print(f"{sys.argv[1]}: {line}") + sys.exit(1 if bad else 0) stages: [commit-msg] From 72b98f62f594e9461f9a1abe545979826961a2b0 Mon Sep 17 00:00:00 2001 From: Ray Walker Date: Sun, 4 Oct 2026 17:09:14 +1100 Subject: [PATCH 5/7] chore: treat only git's own comment lines as comments in the commit-message check --- .pre-commit-config.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 8e91ddf..900c9ac 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -17,7 +17,7 @@ repos: stages: [pre-commit] - id: no-internal-references-commit-msg name: No internal references in commit message - # Same patterns. git hands this hook the raw message file: "#" comment lines, the diff + # Same patterns. git hands this hook the raw message file: "# " comment lines, the diff # below the `git commit -v` scissors line, and its own merge and revert subjects, which # quote branch names and earlier subjects. Only the text the author wrote is checked. language: python @@ -29,7 +29,7 @@ repos: GIT_SUBJECT = re.compile(r"Merge (?:branch|branches|remote-tracking branch|tag|commit) '[^']*'(?: and '[^']*')*(?: of \S+)?(?: into \S+)?|Revert \".*\"") text = open(sys.argv[1], encoding="utf-8", errors="replace").read() text = text.split("# ------------------------ >8 ------------------------")[0] - lines = [line for line in text.splitlines() if line.strip() and not line.startswith("#")] + lines = [line for line in text.splitlines() if line.strip() and not re.match(r"#(?:[ \t]|$)", line)] if lines and GIT_SUBJECT.fullmatch(lines[0]): lines = lines[1:] bad = [line for line in lines if P.search(line)] From b01ef22604ce3dbd1ce23dfe56766c0c9e89de56 Mon Sep 17 00:00:00 2001 From: Ray Walker Date: Sun, 4 Oct 2026 17:11:25 +1100 Subject: [PATCH 6/7] chore: cover every merge subject git writes, and report an unreadable message file --- .pre-commit-config.yaml | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 900c9ac..c363cb0 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -26,8 +26,13 @@ repos: - | import re, sys P = re.compile(r"\b(?i:LAB)-[0-9]+|op://|\.ts\.net|(?i:\bk3s[\s-]+(?:cluster|node|host)s?\b)|dev\.cachekit\.io|\bStage [0-9]|\bAC-[0-9]|github\.com/cachekit(?![\w-])") - GIT_SUBJECT = re.compile(r"Merge (?:branch|branches|remote-tracking branch|tag|commit) '[^']*'(?: and '[^']*')*(?: of \S+)?(?: into \S+)?|Revert \".*\"") - text = open(sys.argv[1], encoding="utf-8", errors="replace").read() + KIND = r"(?:branch|branches|remote-tracking branch|remote-tracking branches|tag|tags|commit|commits)" + GIT_SUBJECT = re.compile(rf"Merge {KIND} '[^']*'(?:(?:, | and ){KIND}? ?'[^']*')*(?: of \S+)?(?: into \S+)?|(?:Revert|Reapply) \".*\"") + try: + with open(sys.argv[1], encoding="utf-8", errors="replace") as f: + text = f.read() + except OSError as e: + sys.exit(f"{sys.argv[1]}: cannot read the commit message: {e}") text = text.split("# ------------------------ >8 ------------------------")[0] lines = [line for line in text.splitlines() if line.strip() and not re.match(r"#(?:[ \t]|$)", line)] if lines and GIT_SUBJECT.fullmatch(lines[0]): From cebb2c5465460ea2e03a23cc931a7cb35f3f778a Mon Sep 17 00:00:00 2001 From: Ray Walker Date: Sun, 4 Oct 2026 17:13:18 +1100 Subject: [PATCH 7/7] chore: accept semicolon-joined merge subjects and the underscore form of the cluster pattern --- .pre-commit-config.yaml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index c363cb0..d1f79f9 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -11,7 +11,7 @@ repos: - id: no-internal-references name: No internal references in docs language: pygrep - entry: '\b(?i:LAB)-[0-9]+|op://|\.ts\.net|(?i:\bk3s[\s-]+(?:cluster|node|host)s?\b)|dev\.cachekit\.io|\bStage [0-9]|\bAC-[0-9]|github\.com/cachekit(?![\w-])' + entry: '\b(?i:LAB)-[0-9]+|op://|\.ts\.net|(?i:\bk3s[\s_-]+(?:cluster|node|host)s?\b)|dev\.cachekit\.io|\bStage [0-9]|\bAC-[0-9]|github\.com/cachekit(?![\w-])' files: ^((packages|crates)/[^/]+/)?README[^/]*$|^docs/ types: [text] stages: [pre-commit] @@ -25,9 +25,9 @@ repos: args: - | import re, sys - P = re.compile(r"\b(?i:LAB)-[0-9]+|op://|\.ts\.net|(?i:\bk3s[\s-]+(?:cluster|node|host)s?\b)|dev\.cachekit\.io|\bStage [0-9]|\bAC-[0-9]|github\.com/cachekit(?![\w-])") + P = re.compile(r"\b(?i:LAB)-[0-9]+|op://|\.ts\.net|(?i:\bk3s[\s_-]+(?:cluster|node|host)s?\b)|dev\.cachekit\.io|\bStage [0-9]|\bAC-[0-9]|github\.com/cachekit(?![\w-])") KIND = r"(?:branch|branches|remote-tracking branch|remote-tracking branches|tag|tags|commit|commits)" - GIT_SUBJECT = re.compile(rf"Merge {KIND} '[^']*'(?:(?:, | and ){KIND}? ?'[^']*')*(?: of \S+)?(?: into \S+)?|(?:Revert|Reapply) \".*\"") + GIT_SUBJECT = re.compile(rf"Merge {KIND} '[^']*'(?:(?:, |; | and ){KIND}? ?'[^']*')*(?: of \S+)?(?: into \S+)?|(?:Revert|Reapply) \".*\"") try: with open(sys.argv[1], encoding="utf-8", errors="replace") as f: text = f.read()