From 9b9d996447d1e8200e37f38ccaae506f9faa42ff Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 8 Aug 2026 21:58:35 +0000 Subject: [PATCH 1/2] docs: show what Commit Check does before explaining why 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. --- profile/README.md | 128 ++++++++++++++++++++++++++++++++++++---------- 1 file changed, 102 insertions(+), 26 deletions(-) diff --git a/profile/README.md b/profile/README.md index 4231f3f..4359f28 100644 --- a/profile/README.md +++ b/profile/README.md @@ -15,26 +15,82 @@ one policy, across your CLI, pre-commit, CI, and AI agents. [![Marketplace](https://img.shields.io/badge/Marketplace-commit--check--action-2c9ccd?logo=githubactions&logoColor=white)](https://github.com/marketplace/actions/commit-check-action) [![License: MIT](https://img.shields.io/badge/License-MIT-2c9ccd.svg)](https://opensource.org/licenses/MIT) [![Website](https://img.shields.io/badge/Website-commit--check.com-2c9ccd?logo=git&logoColor=white)](https://commit-check.com) - + --- -## Why Commit Check +## What it looks like + +```text +CC001 message check failed ==> updated the parser +The commit message should follow Conventional Commits. See https://www.conventionalcommits.org +Suggest: Use (): , where is one of: feat, fix, docs, style, refactor, test, chore, perf, build, ci +Docs: https://commit-check.com/rules/#cc001 +``` + +Every failure names a **stable rule ID**, the value that failed, what to do +about it, and where it is documented. The same verdict is available as JSON, a +job summary, a PR comment, or an MCP tool call — so the thing that fails your +build and the thing your agent reads are the same thing. + +## One policy, four places + +``` + cchk.toml + │ + ┌─────────────────┼─────────────────┬─────────────────┐ + ▼ ▼ ▼ ▼ + your machine pre-commit GitHub CI AI agents + (commit-check) hook Action (MCP) + │ │ │ │ + └─────────────────┴────────┬────────┴─────────────────┘ + ▼ + same rules, same verdict +``` **Commit Check** (aka **cchk**) is an open-source policy engine for Git commit -metadata — commit messages, branch names, committer name/email, signoff, and -more — helping teams keep a **consistent, compliant, and clean Git history**. - -Define your rules once in a single versioned config, and enforce them -identically everywhere: on a developer's machine, in CI, and in AI-assisted -workflows. - -It's a lightweight, open alternative to GitHub Enterprise -[metadata restrictions](https://docs.github.com/en/enterprise-server@3.11/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets#metadata-restrictions) -and Bitbucket's paid -[Yet Another Commit Checker](https://marketplace.atlassian.com/apps/1211854/yet-another-commit-checker?tab=overview&hosting=datacenter), -built for a modern DevOps and Infrastructure-as-Code workflow. +metadata — commit messages, branch names, committer name and email, signoff, +and more. + +Write the rules once in a versioned TOML file and every enforcement point reads +that same file, so a commit that passes on a laptop passes in CI, and an agent +asking *"would this message be accepted?"* gets the answer your maintainers +actually configured. Organizations can go one step further: `inherit_from` +points at a shared config, and each repository overrides only what it must. + +## Quick start + +There is nothing to configure to begin with. Out of the box it enforces +Conventional Commits, Conventional Branch, and sane subject lengths. + +**As a pre-commit hook** — feedback while the message is still being written: + +```yaml +# .pre-commit-config.yaml +repos: + - repo: https://github.com/commit-check/commit-check + rev: v2.13.4 + hooks: + - id: check-message + - id: check-branch +``` + +**In GitHub Actions** — where it stops being a suggestion and becomes a policy: + +```yaml +# .github/workflows/commit-check.yml +- uses: commit-check/commit-check-action@v2 + with: + message: true + branch: true + pr-title: true + job-summary: true + pr-comments: true # needs permissions: pull-requests: write +``` + +The full walkthrough, every rule, and the configuration reference live at +**[commit-check.com](https://commit-check.com)**. ## The Commit Check family @@ -45,21 +101,41 @@ built for a modern DevOps and Infrastructure-as-Code workflow. | [**commit-check-mcp**](https://github.com/commit-check/commit-check-mcp) | Model Context Protocol server | Letting AI agents validate against your rules | -## Key features +## What it does not do + +Worth knowing before you adopt it: -- ✅ **Conventional Commits** & **Conventional Branch** enforcement -- ✅ **Author** name / email validation with configurable patterns -- ✅ **Signoff (DCO)** verification -- ✅ **Rebase / merge-base** and **force-push** safety checks -- ✅ **AI attribution governance** — detect or forbid AI-generated commit trailers -- ✅ **One config** (`cchk.toml`), with org-level inheritance, shared across CLI, pre-commit & CI -- ✅ **Job summaries & PR comments**, plus **JSON output** and **MCP tools** for automation and AI agents +- It reads commit **metadata** — messages, branch names, author identity, + signoff, push safety. It does not read your code, and it is not a linter. +- A pre-commit hook can be skipped with `--no-verify`. Only the CI check is + really a policy; the hook is there to save you the round trip. +- Imperative-mood checking judges a word's *form*, so a subject led by a noun + that looks like a gerund (`fix: spelling in the docs`) gets reported. Reading + the ending cannot tell those two apart. -## Trusted & secure +## Where Commit Check fits -- 🔒 **SLSA Level 3** build provenance, with artifact attestation verified at install time -- 🏢 Used by teams at **Apache**, **Texas Instruments**, **Mila**, and [many more](https://github.com/commit-check/commit-check-action/network/dependents) -- 📖 **MIT licensed**, actively maintained, and following [Conventional Commits](https://www.conventionalcommits.org/) and [Conventional Branch](https://conventional-branch.github.io/) +Commit metadata rules are usually behind a paid tier. GitHub's +[metadata restrictions](https://docs.github.com/en/enterprise-server@3.11/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets#metadata-restrictions) +need Enterprise; Bitbucket's equivalent, +[Yet Another Commit Checker](https://marketplace.atlassian.com/apps/1211854/yet-another-commit-checker?tab=overview&hosting=datacenter), +is a paid Marketplace app. Commit Check is the open alternative — and because +the policy is a file in your repository rather than a settings page, it can be +reviewed, diffed, and rolled back like anything else you version. + +- 🔒 **SLSA Level 3 build provenance.** Every release carries a signed + attestation you can check yourself: + + ```console + $ pip download commit-check --no-deps -d . + $ gh attestation verify commit_check-*.whl --repo commit-check/commit-check + ``` + +- 🏢 Runs in repositories across **Apache**, **Texas Instruments**, **Mila**, + and [many more](https://github.com/commit-check/commit-check-action/network/dependents) +- 📖 MIT licensed, actively maintained, and itself following + [Conventional Commits](https://www.conventionalcommits.org/) and + [Conventional Branch](https://conventional-branch.github.io/) ## Get involved From c4c1b5959546e47acf9346b0dc2587bcaef0194d Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 8 Aug 2026 22:08:42 +0000 Subject: [PATCH 2/2] docs: remove prose the new structure made redundant 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.) --- profile/README.md | 82 ++++++++++++++++------------------------------- 1 file changed, 28 insertions(+), 54 deletions(-) diff --git a/profile/README.md b/profile/README.md index 4359f28..b253ac5 100644 --- a/profile/README.md +++ b/profile/README.md @@ -7,8 +7,7 @@ Commit Check — Clean commits. Clear standards. -Enforce commit message, branch naming, author, and signoff standards — -one policy, across your CLI, pre-commit, CI, and AI agents. +An open policy engine for Git commit metadata — one versioned file, enforced everywhere. [![PyPI](https://img.shields.io/pypi/v/commit-check?logo=pypi&logoColor=white&color=2c9ccd)](https://pypi.org/project/commit-check/) [![Downloads](https://img.shields.io/pypi/dm/commit-check?color=2c9ccd)](https://pypi.org/project/commit-check/) @@ -25,14 +24,13 @@ one policy, across your CLI, pre-commit, CI, and AI agents. ```text CC001 message check failed ==> updated the parser The commit message should follow Conventional Commits. See https://www.conventionalcommits.org -Suggest: Use (): , where is one of: feat, fix, docs, style, refactor, test, chore, perf, build, ci +Suggest: Use (): , where is one of: feat, fix, docs, ... Docs: https://commit-check.com/rules/#cc001 ``` Every failure names a **stable rule ID**, the value that failed, what to do -about it, and where it is documented. The same verdict is available as JSON, a -job summary, a PR comment, or an MCP tool call — so the thing that fails your -build and the thing your agent reads are the same thing. +about it, and where it is documented — as text, JSON, a job summary, a PR +comment, or an MCP tool call. ## One policy, four places @@ -49,25 +47,17 @@ build and the thing your agent reads are the same thing. same rules, same verdict ``` -**Commit Check** (aka **cchk**) is an open-source policy engine for Git commit -metadata — commit messages, branch names, committer name and email, signoff, -and more. - -Write the rules once in a versioned TOML file and every enforcement point reads -that same file, so a commit that passes on a laptop passes in CI, and an agent -asking *"would this message be accepted?"* gets the answer your maintainers -actually configured. Organizations can go one step further: `inherit_from` -points at a shared config, and each repository overrides only what it must. +Write the rules once. Every surface reads that same file, so a commit that +passes on a laptop passes in CI — and an agent asking *"would this message be +accepted?"* gets the answer your maintainers actually configured. ## Quick start -There is nothing to configure to begin with. Out of the box it enforces -Conventional Commits, Conventional Branch, and sane subject lengths. - -**As a pre-commit hook** — feedback while the message is still being written: +Nothing to configure to begin with: the defaults enforce Conventional Commits, +Conventional Branch, and sane subject lengths. ```yaml -# .pre-commit-config.yaml +# .pre-commit-config.yaml — feedback while the message is still being written repos: - repo: https://github.com/commit-check/commit-check rev: v2.13.4 @@ -76,21 +66,17 @@ repos: - id: check-branch ``` -**In GitHub Actions** — where it stops being a suggestion and becomes a policy: - ```yaml -# .github/workflows/commit-check.yml +# .github/workflows/commit-check.yml — where it becomes a policy, not a suggestion - uses: commit-check/commit-check-action@v2 with: message: true branch: true pr-title: true - job-summary: true pr-comments: true # needs permissions: pull-requests: write ``` -The full walkthrough, every rule, and the configuration reference live at -**[commit-check.com](https://commit-check.com)**. +Every rule and option is at **[commit-check.com](https://commit-check.com)**. ## The Commit Check family @@ -103,44 +89,32 @@ The full walkthrough, every rule, and the configuration reference live at ## What it does not do -Worth knowing before you adopt it: - -- It reads commit **metadata** — messages, branch names, author identity, - signoff, push safety. It does not read your code, and it is not a linter. -- A pre-commit hook can be skipped with `--no-verify`. Only the CI check is - really a policy; the hook is there to save you the round trip. -- Imperative-mood checking judges a word's *form*, so a subject led by a noun - that looks like a gerund (`fix: spelling in the docs`) gets reported. Reading - the ending cannot tell those two apart. +- It reads commit **metadata**, not your code. It is not a linter. +- A pre-commit hook can be skipped with `--no-verify`, so only the CI check is + really a policy — the hook is there to save you the round trip. +- Imperative-mood checking reads a word's *form*, so a subject led by a noun + that looks like a gerund (`fix: spelling in the docs`) gets reported. ## Where Commit Check fits -Commit metadata rules are usually behind a paid tier. GitHub's +Commit metadata rules are usually behind a paid tier: GitHub's [metadata restrictions](https://docs.github.com/en/enterprise-server@3.11/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets#metadata-restrictions) -need Enterprise; Bitbucket's equivalent, +need Enterprise, and Bitbucket's equivalent is [Yet Another Commit Checker](https://marketplace.atlassian.com/apps/1211854/yet-another-commit-checker?tab=overview&hosting=datacenter), -is a paid Marketplace app. Commit Check is the open alternative — and because -the policy is a file in your repository rather than a settings page, it can be +a paid Marketplace app. Commit Check is the open alternative — and because the +policy is a file in your repository rather than a settings page, it can be reviewed, diffed, and rolled back like anything else you version. -- 🔒 **SLSA Level 3 build provenance.** Every release carries a signed - attestation you can check yourself: - - ```console - $ pip download commit-check --no-deps -d . - $ gh attestation verify commit_check-*.whl --repo commit-check/commit-check - ``` - -- 🏢 Runs in repositories across **Apache**, **Texas Instruments**, **Mila**, - and [many more](https://github.com/commit-check/commit-check-action/network/dependents) +- 🔒 **SLSA Level 3 build provenance** — verify any release yourself with + `gh attestation verify --repo commit-check/commit-check` +- 🏢 Runs in repositories across **Apache**, **Texas Instruments**, **Mila**, and + [many more](https://github.com/commit-check/commit-check-action/network/dependents) - 📖 MIT licensed, actively maintained, and itself following [Conventional Commits](https://www.conventionalcommits.org/) and [Conventional Branch](https://conventional-branch.github.io/) ## Get involved -We welcome feedback, bug reports, and feature requests from the community. - -- [Issues](https://github.com/commit-check/commit-check/issues) — bug reports & feature requests -- [Discussions](https://github.com/commit-check/commit-check/discussions) — questions, ideas, and community conversations -- [Documentation](https://commit-check.com) — guides, configuration reference, and more +[Issues](https://github.com/commit-check/commit-check/issues) for bugs and feature +requests · [Discussions](https://github.com/commit-check/commit-check/discussions) +for questions and ideas · [Docs](https://commit-check.com) for everything else.