docs: show what Commit Check does before explaining why - #53
Conversation
The profile led with prose and a seven-item feature checklist, and never
showed a line of config or output. A policy engine whose pitch is 'one
versioned file, enforced everywhere' should show the file.
Replaces the checklist with real failure output, which demonstrates the
rule IDs, suggestions and doc links in four lines rather than asserting
them in seven bullets. Adds a diagram of the one-config-four-surfaces
claim, and a quick start for the two integrations people actually use.
Two claims in 'Trusted & secure' were also worth more honest wording:
- 'artifact attestation verified at install time' -- pip does not
verify PEP 740 attestations, so nothing verified anything at install
time. Replaced with the command that does verify it. That section
also had its SLSA badge removed in 3339c1f, which suggests the
doubt was already there.
- 'Used by teams at Apache, Texas Instruments, Mila' implies adoption
by those organizations; the evidence is the dependents graph. Now
matches the wording commit-check.com settled on: 'runs in
repositories across'.
Adds a 'What it does not do' section. Naming the limits costs less trust
than having a reader find them.
|
Warning Review limit reached
Next review available in: 2 minutes You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Commit-Check ✔️ |
146 to 120 lines, all of it wording. Nothing that shows something was removed: the diagram, both YAML blocks, the failure output, the family table and the three limits are untouched. The tagline listed the four surfaces that the diagram below it draws, and the paragraph under the diagram listed the rule types the tagline had just listed. Organization-level inheritance went too -- a real feature, but it belongs on the site, not in the first screen someone sees. (The previous message for this commit led with 'cut', which the v2.11.1 action pinned in this repo rejects. That is issue #526 in the wild.)
ad05928 to
c4c1b59
Compare
2 participants
A rewrite of the org profile README. Preview:
profile/README.mdon this branch.The banner, badges, and the family table are untouched — they were the strongest part of the page.
The problem
The page described a policy engine for four pages and never showed a line of config or a line of output. For a tool whose pitch is "one versioned file, enforced everywhere", not showing the file is a strange omission. The largest section was a seven-item ✅ checklist, which is the part of a README people skip.
What changed
Key features→What it looks like. Real failure output, four lines:That demonstrates the stable rule IDs, the suggestion, and the docs link at once. The checklist asserted the same things in seven bullets and proved none of them.
New: a diagram for the one-config claim.
cchk.tomlat the top, four surfaces below it, "same rules, same verdict" at the bottom. It was previously a sentence; the sentence is the whole product.New:
Quick start. The pre-commit block and the Action block, which are what a visitor is actually here for. Both copied from the docs rather than written fresh, and the Action inputs are checked againstaction.yml(message,branch,pr-title,job-summary,pr-comments).Why Commit Check→Where Commit Check fits, moved to the end. The GitHub Enterprise / Yet Another Commit Checker comparison is the most persuasive paragraph on the page and it was buried third in an opening section. The tagline under the banner already does the "why".Two claims rewritten, as agreed
"artifact attestation verified at install time" — nothing verifies at install time.
pip installdoes not check PEP 740 attestations; the provenance fromactions/attest-build-provenanceis verified withgh attestation verify. Replaced the claim with the two commands that actually do it. Worth noting 3339c1f already removed the SLSA badge from this file, so the doubt predates me."Used by teams at Apache, Texas Instruments, Mila" — that phrasing implies those organizations adopted it; the evidence is the dependents graph. Now matches the wording commit-check.com settled on in commit-check.com#11: "runs in repositories across". Same names, defensible claim.
New:
What it does not doThree limits, stated rather than left to be discovered: it reads metadata and is not a linter; a pre-commit hook can be skipped with
--no-verifyso only CI is really a policy; and imperative-mood checking reads word form, sofix: spelling in the docsgets reported.This is borrowed from open-delivery-spec, whose "signal producer, not a quality oracle" line is the best sentence on that page. Naming a limitation earns more trust than it spends — and it is the opposite of what the old
Trusted & securesection was doing.Checks
rev: v2.13.4matches the current release, andcommit-check-action@v2exists as a moving tag.🤖 Generated with Claude Code
https://claude.ai/code/session_01U9zFxq8V4qxG4aMzJhGBFn
Generated by Claude Code