From fc5915dfa9efef17597fdb2dcfbb76157db747c8 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 5 Aug 2026 14:53:53 +0000 Subject: [PATCH 1/4] docs: file troubleshooting where someone with a red build would look MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The nav had three groups, and the third was "About": migration, troubleshooting and the changelog. None of those is about the project. Troubleshooting is the one that mattered. It is the page you want when a check has just failed, and nobody looks under "About" for that — it had exactly one inbound link in the whole site, buried in a collapsed admonition, so the nav was doing nearly all the work of making it findable and the nav had it filed wrong. Two groups now, split by what the reader is doing rather than what the page is: Guides are followed to get something done, Reference is looked a fact up in. Troubleshooting and migration join the guides, the changelog joins the reference, and "About" is gone. Section names are not URLs, so nothing needs a redirect. Also link troubleshooting from "Where to go next" on the getting started page — the first failure tends to arrive shortly after the first success — and fix a link that still called the migration page by its old title. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01U9zFxq8V4qxG4aMzJhGBFn --- docs/changelog.md | 2 +- docs/getting-started.md | 3 +++ mkdocs.yml | 14 +++++++++++--- 3 files changed, 15 insertions(+), 4 deletions(-) diff --git a/docs/changelog.md b/docs/changelog.md index 06ec4c7..b3d2a6f 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -281,7 +281,7 @@ Configuration Format: * `.commit-check.yml` has been replaced with `cchk.toml` or `commit-check.toml`. * All YAML configurations must be migrated to TOML from this version onward. -* See the [Migration Guide](migration.md) for step-by-step instructions. +* See [Migrating from v1](migration.md) for step-by-step instructions. Removed Pre-commit Hooks and CLI Options: diff --git a/docs/getting-started.md b/docs/getting-started.md index b3af7d4..6159745 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -187,3 +187,6 @@ $ gh attestation verify commit_check-*.whl --repo commit-check/commit-check plus the environment variable and CLI flag that override it. - **[Command-line recipes](example.md)** — checking a range, wiring up CI, reading the JSON output. +- **[Troubleshooting](troubleshoot.md)** — a check failing that you did not + turn on, nothing running at all, and how to get a commit through when you + have to. diff --git a/mkdocs.yml b/mkdocs.yml index 5b6975f..04528e0 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -139,6 +139,15 @@ plugins: hooks: - scripts/mkdocs_hooks.py +# Two groups, split by what the reader is doing: Guides are pages you follow to +# get something done, Reference is what you look a fact up in. The pages are +# ordered within each group by how often they are needed. +# +# There was a third group, "About", holding migration, troubleshooting and the +# changelog — none of which is about the project. Troubleshooting was the +# problem: it is the page you want when a build has just gone red, and nobody +# looks under "About" for that. It has exactly one inbound link in the whole +# site, so the nav was doing nearly all the work of making it findable. nav: - Home: index.md - Getting started: getting-started.md @@ -146,12 +155,11 @@ nav: - Integrations: guides/integrations.md - Policy guides: guides/policies.md - Command-line recipes: example.md + - Troubleshooting: troubleshoot.md + - Migrating from v1: migration.md - Reference: - Rules: rules.md - Configuration: configuration.md - - About: - - Migrating from v1: migration.md - - Troubleshooting: troubleshoot.md - Changelog: changelog.md - Blog: - blog/index.md From 01121d821be5f4f46a88e0fe39ee24681b1603f1 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 5 Aug 2026 14:58:30 +0000 Subject: [PATCH 2/4] docs: put the install command before the second round of argument MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The landing page made its case three times before telling anyone what to run. "Why it exists" (279 words) was followed immediately by four cards restating it, then six more cards, then two more sections — thirteen cards across three grids, with `pip install` at line 350. Two of those four cards were the prose again in shorter form. "One config" is already the heading of the section above it and the closing line of the prose; "Stable rule IDs" is that same closing line's second half. The grid is gone, and the two points that were not duplicates are kept where they land better: enforcement being cheapest in the hook joins the paragraph it elaborates, and SLSA provenance moves next to the install command, which is where "can I trust this package" comes up. The install block now sits directly after the tabs, so a reader who arrived already convinced gets the command at 876px instead of 3000, and one who needs convincing still has the prose immediately below it. Its heading claimed two minutes while the page its own button links to says five. Neither number was doing any work, and the section shows two commands, so it says that instead. Nine cards in two grids, down from thirteen in three. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01U9zFxq8V4qxG4aMzJhGBFn --- docs/index.md | 68 ++++++++++++++------------------------------------- 1 file changed, 19 insertions(+), 49 deletions(-) diff --git a/docs/index.md b/docs/index.md index 60710d0..42aa368 100644 --- a/docs/index.md +++ b/docs/index.md @@ -68,6 +68,21 @@ whatever your AI agent is committing on your behalf. } ``` +## Start with two commands + +```console +$ pip install commit-check +$ commit-check --message --branch +``` + +No configuration file needed to start — sensible defaults apply immediately, and +you tighten them when you are ready. Releases carry +[SLSA Level 3](https://slsa.dev) build provenance, so you can verify an artifact +came from this repository's pipeline before you install it. + +[Get started :octicons-arrow-right-24:](getting-started.md){ .md-button .md-button--primary } +[Rules reference](rules.md){ .md-button } + ## Why it exists Git history is a database that every team writes to and almost nobody validates. @@ -84,42 +99,10 @@ looking, and only after the work is done. Commit Check treats commit metadata the way linters treat code: a policy written down once, enforced identically everywhere, with a stable identifier for every -diagnostic so findings can be discussed, cited, and tracked. - -
- -- :material-file-cog-outline:{ .lg .middle } __One config__ - - --- - - A single `cchk.toml` drives the CLI, the pre-commit hook, the GitHub Action - and the MCP server. There is no second place where the rules can disagree - with themselves. - -- :material-lightning-bolt-outline:{ .lg .middle } __Fails where it is cheap__ - - --- - - The same check that runs in CI runs in your `commit-msg` hook. A malformed - subject costs a second locally, or a full CI cycle plus a force-push - remotely. - -- :material-tag-outline:{ .lg .middle } __Stable rule IDs__ - - --- - - Every rule has an ID like `CC003` that never changes once released. Cite it - in a review comment, link to its documentation, suppress it per-rule. - -- :material-shield-check:{ .lg .middle } __Built to be trusted__ - - --- - - SLSA Level 3 build provenance with artifact attestation you can verify - before installing. A failure names the rule, quotes the offending value, - and says how to fix it. - -
+diagnostic so findings can be discussed, cited, and tracked. And enforced where +it is cheapest — the check that runs in CI is the same one that runs in your +`commit-msg` hook, where a malformed subject costs a second to fix rather than a +full CI cycle and a force-push. ## What it checks @@ -347,19 +330,6 @@ graph TB And [many more](https://github.com/commit-check/commit-check-action/network/dependents). -## Ready in two minutes - -```console -$ pip install commit-check -$ commit-check --message --branch -``` - -No configuration file needed to start — sensible defaults apply immediately, and -you tighten them when you are ready. - -[Get started :octicons-arrow-right-24:](getting-started.md){ .md-button .md-button--primary } -[Rules reference](rules.md){ .md-button } - ---
From 7db24ef817d8396cd46a833ee7709393b96926fa Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 5 Aug 2026 15:10:45 +0000 Subject: [PATCH 3/4] docs: make the three tabs demonstrate the same two checks MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The section is headed "One config, enforced everywhere" and says the same rules run on a laptop and in CI. The tabs under it showed three different check sets: the CLI ran message and branch, pre-commit added check-author-email, and the Action ran message and branch — where author-email defaults to false in action.yml, so it was not running there at all. The illustration contradicted the sentence it illustrates. Dropping the author-email hook makes all three exactly message plus branch, which is the parallel the section is claiming. The full hook list already lives in the integrations guide, where it is the subject rather than an aside. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01U9zFxq8V4qxG4aMzJhGBFn --- docs/index.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index 42aa368..1fe1add 100644 --- a/docs/index.md +++ b/docs/index.md @@ -40,7 +40,6 @@ whatever your AI agent is committing on your behalf. hooks: - id: check-message - id: check-branch - - id: check-author-email ``` === "GitHub Actions" From d37edb7c15ec3aba28a605db6848ef5742e337e7 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 5 Aug 2026 15:17:54 +0000 Subject: [PATCH 4/4] docs: correct two examples in "Why it exists" and say which rules start off MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The section justifies the tool with four concrete costs. Checking each against the rule it depends on turned up two problems. The bisect example gave the right conclusion for the wrong reason. Merge commits recording "nothing but a sync" is a complaint about noise, and noise is a `git log` problem. What merges actually do to a bisect is make the result ambiguous: the run ends on a merge, and the change that broke the build could be in either parent or in the resolution. That is also the reason someone would forbid them, so the example now says it. The signoff example said a contribution "has to be rejected" months later. That is not what happens — a missing trailer is remediated by rewriting the branch with `--signoff`. The sting is the same and this version is true, which matters in a paragraph whose whole force comes from the examples being real. Then the gap worth closing: of those four costs, only the first is prevented by a default install. Merge commits are permitted unless you forbid them and signoff is not required unless you require it, so a reader following the install command directly above this section would still hit two of the four. Rather than swap the examples for tamer ones that happen to be on, name the split — those two are decisions rather than defects, and a tool that made them for you would be overreaching. That also sets up "What it is not" further down the page. Splitting the closing paragraph in passing: the enforcement-is-cheap point and the linter analogy were one 62-word run. Reordering rather than just splitting them keeps the analogy last, where it reads as a close instead of needing an "And" to bolt it on. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01U9zFxq8V4qxG4aMzJhGBFn --- docs/index.md | 24 ++++++++++++++++-------- 1 file changed, 16 insertions(+), 8 deletions(-) diff --git a/docs/index.md b/docs/index.md index 1fe1add..a41a0fc 100644 --- a/docs/index.md +++ b/docs/index.md @@ -87,22 +87,30 @@ came from this repository's pipeline before you install it. Git history is a database that every team writes to and almost nobody validates. The cost shows up later, and indirectly. Release notes get written by hand -because commit subjects cannot be grouped. `git bisect` walks through merge -commits that record nothing but a sync. A commit is attributed to `ec2-user` -because a build box had no `user.name`. A contribution has to be rejected months -after the fact because it never carried a `Signed-off-by` trailer. +because commit subjects cannot be grouped. A `git bisect` ends on a merge +commit, where the change that broke the build could be in either parent or in +the resolution. A commit is attributed to `ec2-user` because a build box had no +`user.name`. A branch has its history rewritten months later because none of its +commits carried a `Signed-off-by` trailer. None of these are caught by a linter, a type checker, or a test suite. They are all caught by review — which means inconsistently, by whoever happens to be looking, and only after the work is done. -Commit Check treats commit metadata the way linters treat code: a policy written -down once, enforced identically everywhere, with a stable identifier for every -diagnostic so findings can be discussed, cited, and tracked. And enforced where -it is cheapest — the check that runs in CI is the same one that runs in your +Commit Check makes them mechanical instead, and catches them where it is +cheapest: the check that runs in CI is the same one that runs in your `commit-msg` hook, where a malformed subject costs a second to fix rather than a full CI cycle and a force-push. +It treats commit metadata the way linters treat code — a policy written down +once, enforced identically everywhere, with a stable identifier for every +diagnostic so findings can be discussed, cited, and tracked. + +Not all of that policy is on to begin with. Two of the four problems above are +decisions rather than defects — whether merge commits belong in your history, +and whether contributors must sign off — and they stay off until you make them. +The [rules reference](rules.md#rule-index) marks which rules start on. + ## What it checks