Skip to content

docs: sharpen README first screen — lightweight policy engine framing #418

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
shenxianpeng merged 1 commit into from
May 29, 2026
Merged

docs: sharpen README first screen — lightweight policy engine framing #418

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 8 additions & 3 deletions README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,10 +39,15 @@ Commit Check
Overview
--------

**Commit Check** (aka **cchk**) is the most comprehensive open-source tool for enforcing Git commit standards — including commit messages, branch naming, author identity, commit signoff, and more — helping teams maintain consistency and compliance across every repository.
**Commit Check** is a lightweight policy engine for Git commit metadata.

As a lightweight, free 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>`_ plugin, Commit Check integrates DevOps principles and Infrastructure as Code (IaC) practices for a modern workflow.
It validates commit messages, branch names, author identity, signoff trailers,
and push safety — using one versioned TOML policy across local hooks, CI,
GitHub Actions, and AI automation.

- **One policy file:** ``cchk.toml``
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot May 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Clarify "one policy file" when two filenames are supported.

Line 48 states "One policy file: cchk.toml", but lines 111 and 123 in the README mention both cchk.toml and commit-check.toml as supported configuration filenames. This could confuse readers who might think only cchk.toml works.

Consider revising to acknowledge both filenames while emphasizing the single-policy-file concept, e.g., "One policy file: cchk.toml (or commit-check.toml)" or "One policy file: cchk.toml*" with a footnote.

📝 Proposed clarification 
-**One policy file:** ``cchk.toml``
+**One policy file:** ``cchk.toml`` (or ``commit-check.toml``)
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
- **One policy file:** ``cchk.toml``
- **One policy file:** ``cchk.toml`` (or ``commit-check.toml``)
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@README.rst` at line 48, Update the README sentence that currently says "One
policy file: cchk.toml" to mention both supported filenames so readers aren't
misled; change it to something like "One policy file: cchk.toml (or
commit-check.toml)" or add a footnote explaining that the tool accepts either
cchk.toml or commit-check.toml while still enforcing a single policy file;
ensure references to the filenames cchk.toml and commit-check.toml in the README
are consistent.

- **Multiple enforcement points:** CLI, pre-commit, CI / GitHub Actions
- **Machine-readable output:** JSON + Python API for automation and AI agents
Comment on lines +48 to +50
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot May 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Description: Verify core differentiators are implemented

# 1. Check for policy file at root
echo "=== 1. Policy file at root ==="
fd -t f "^(cchk|commit-check)\.toml$" --max-depth 1

# 2. Verify no action.yml exists (confirming "CI / GitHub Actions" vs "GitHub Action")
echo -e "\n=== 2. Check for action.yml (should NOT exist) ==="
fd -t f "^action\.ya?ml$" --max-depth 1
if [ $? -ne 0 ]; then
  echo "✓ No action.yml found (confirms 'CI / GitHub Actions' wording)"
fi

# 3. Check for --format json implementation
echo -e "\n=== 3. JSON output implementation ==="
rg -n "format.*json|--format|argparse.*format" commit_check/main.py -C3 | head -30

# 4. Verify Python API functions
echo -e "\n=== 4. Python API functions ==="
rg -n "^def (validate_message|validate_branch|validate_author|validate_push|validate_all)" commit_check/api.py -A 1

# 5. Check for pre-commit hooks file
echo -e "\n=== 5. Pre-commit hooks file ==="
fd -t f "pre-commit-hooks\.ya?ml$"
if [ -f .pre-commit-hooks.yaml ]; then
  echo "Found .pre-commit-hooks.yaml"
  rg "^\s+- id:" .pre-commit-hooks.yaml
fi

Repository: commit-check/commit-check

Length of output: 1262

Confirm differentiators (policy file, JSON output, Python API, pre-commit hooks) and tighten CI/GitHub Actions wording

  • Policy file: cchk.toml exists at repo root.
  • “CI / GitHub Actions”: no action.yml / action.yaml exists at repo root.
  • JSON output: implemented via --format choices ["text","json"] and a output_format == "json" branch that emits machine-readable results.
  • Python API: commit_check/api.py defines validate_message, validate_branch, validate_push, validate_author, and validate_all.
  • Pre-commit: .pre-commit-hooks.yaml exists (can’t confirm the “5 hooks” count from the current evidence).
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@README.rst` around lines 48 - 50, Update the README wording to accurately
reflect available differentiators: state that a policy file cchk.toml exists at
the repository root; describe machine-readable output as supported via the CLI
--format option (["text","json"]) and the output_format == "json" branch that
emits JSON; reference the Python API by naming the functions in
commit_check/api.py (validate_message, validate_branch, validate_push,
validate_author, validate_all); note that pre-commit integration is present via
.pre-commit-hooks.yaml but do not assert a specific hook count; and tighten the
CI/GitHub Actions claim to indicate CI integrations are supported but no
action.yml/action.yaml is present at the repo root.


.. image:: https://github.com/commit-check/commit-check/raw/main/docs/demo.gif
:alt: commit-check demo
Expand Down