Skip to content

docs: consolidate the site from 17 pages to 10 #4

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 4 commits into from
Aug 4, 2026
+759 −882
Merged

docs: consolidate the site from 17 pages to 10 #4

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
b57c8d6
docs: file the signoff fixes under v2.11.1, where they shipped
claude Aug 4, 2026
2a09dfa
docs: consolidate 17 pages into 10 and guard the cross-links
claude Aug 4, 2026
410bc33
docs: point the pre-commit examples at v2.13.0
claude Aug 4, 2026
3a62d91
ci: check the docs against the released package, not main
claude Aug 4, 2026
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
19 changes: 12 additions & 7 deletions .github/workflows/deploy.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,15 +25,20 @@ jobs:
with:
python-version: '3.x'

# Installed from main rather than PyPI: the site documents rule IDs that
# are merged but not yet released, so the published package would report
# a spurious mismatch. Switch this to the released package once a version
# carrying them is on PyPI.
- name: Install commit-check from main
# The released package, deliberately unpinned. This site documents the
# version a reader can actually install, so the check is only meaningful
# against that — pinning would let the two drift apart silently until
# somebody bumped the pin.
#
# This used to install from main, because the rule IDs the site documents
# were merged but unreleased and PyPI would have reported a spurious
# mismatch. v2.13.0 shipped them, so the exception is over. If a future
# release is documented here ahead of time, point this back at main for
# as long as that is true, and no longer.
- name: Install the released commit-check
run: |
python -m pip install --upgrade pip
python -m pip install pytest
python -m pip install "commit-check @ git+https://github.com/commit-check/commit-check@main"
python -m pip install pytest commit-check

- name: Check the docs against the package
run: pytest tests/ -q
Expand Down
66 changes: 45 additions & 21 deletions docs/changelog.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,25 @@ All **notable changes** to this project will be documented in this file.

Full changelog available at [GitHub releases](https://github.com/commit-check/commit-check/releases).

## v2.13.0 (2026-08-04)
## Highlights

The releases worth knowing about, newest first. Each links to its full entry
below and to the page that documents the feature properly.

| Version | What changed | Documented in |
|---|---|---|
| [2.13.0](#v2130) | Stable rule IDs in terminal output and JSON | [Rules reference](rules.md) |
| [2.12.0](#v2120) | Author name and email patterns became configurable | [CC101](rules.md#cc101) · [CC102](rules.md#cc102) |
| [2.11.0](#v2110) | AI attribution policy | [Policy guides](guides/policies.md#ai-attribution) |
| [2.10.0](#v2100) | `dependabot/` and `renovate/` branches accepted by default | [CC201](rules.md#cc201) |
| [2.9.0](#v290) | AI agent branch prefixes accepted by default | [CC201](rules.md#cc201) |
| [2.8.0](#v280) | Custom `message_pattern`; Python 3.9 dropped | [CC001](rules.md#cc001) |
| [2.7.0](#v270) | Force push blocking | [CC301](rules.md#cc301) |
| [2.6.0](#v260) | `--format json`, `--compact`, `--no-banner` | [Command-line recipes](example.md#output-for-scripts-and-ci) |
| [2.5.0](#v250) | Organization-wide config with `inherit_from` | [Integrations](guides/integrations.md#across-an-organization) |
| [2.0.0](#v200) | Configuration moved from YAML to TOML — breaking | [Migrating from v1](migration.md) |

## v2.13.0 (2026-08-04) { #v2130 }

### New Features

Expand Down Expand Up @@ -35,11 +53,12 @@ Full changelog available at [GitHub releases](https://github.com/commit-check/co
* The documentation, the landing page and the blog moved to
[commit-check.com](https://commit-check.com) and are published from one
domain. `docs.commit-check.com` URLs redirect.
See PRs [#515](https://github.com/commit-check/commit-check/pull/515),
See PRs [#514](https://github.com/commit-check/commit-check/pull/514),
[#515](https://github.com/commit-check/commit-check/pull/515),
[#518](https://github.com/commit-check/commit-check/pull/518) and
[#519](https://github.com/commit-check/commit-check/pull/519).

## v2.12.2 (2026-08-01)
## v2.12.2 (2026-08-01) { #v2122 }

### Bug Fixes

Expand All @@ -53,7 +72,7 @@ Full changelog available at [GitHub releases](https://github.com/commit-check/co
rejected by `subject_imperative`.
See PR [#496](https://github.com/commit-check/commit-check/pull/496).

## v2.12.1 (2026-07-31)
## v2.12.1 (2026-07-31) { #v2121 }

### Bug Fixes

Expand All @@ -63,13 +82,13 @@ Full changelog available at [GitHub releases](https://github.com/commit-check/co
* Hardened the `pip install` step flagged by SonarCloud code scanning.
See PR [#479](https://github.com/commit-check/commit-check/pull/479).

## v2.12.0 (2026-07-24)
## v2.12.0 (2026-07-24) { #v2120 }

### New Features

* **Configurable author patterns** — `author_name` and `author_email` accept a
custom regex, so organisations can require their own naming or email domain
instead of the built-in patterns.
* **Configurable author patterns** — `author_name_pattern` and
`author_email_pattern` accept a custom regex, so organisations can require
their own naming or email domain instead of the built-in patterns.
See PR [#459](https://github.com/commit-check/commit-check/pull/459).

### Bug Fixes
Expand All @@ -82,12 +101,17 @@ Full changelog available at [GitHub releases](https://github.com/commit-check/co
to the last commit's author. A misconfigured identity used to pass whenever
the previous commit happened to be valid.
See PR [#461](https://github.com/commit-check/commit-check/pull/461).

## v2.11.1 (2026-07-09) { #v2111 }

### Bug Fixes

* `require_signed_off_by` accepts any name, and is skipped for authors listed
in `ignore_authors`.
See PRs [#462](https://github.com/commit-check/commit-check/pull/462) and
[#464](https://github.com/commit-check/commit-check/pull/464).

## v2.11.0 (2026-07-06)
## v2.11.0 (2026-07-06) { #v2110 }

### New Features

Expand All @@ -108,7 +132,7 @@ Full changelog available at [GitHub releases](https://github.com/commit-check/co
* Migrated PyPI publishing to `pypa/gh-action-pypi-publish`
* Removed OpenSSF Scorecard badge after evaluation (moved to Scorecard dashboard)

## v2.10.1 (2026-06-30)
## v2.10.1 (2026-06-30) { #v2101 }

### Bug Fixes

Expand All @@ -126,7 +150,7 @@ Full changelog available at [GitHub releases](https://github.com/commit-check/co
* Removed legacy YAML config parsing code from `util.py`.
See PR [#444](https://github.com/commit-check/commit-check/pull/444).

## v2.10.0 (2026-06-26)
## v2.10.0 (2026-06-26) { #v2100 }

### New Features

Expand All @@ -135,7 +159,7 @@ Full changelog available at [GitHub releases](https://github.com/commit-check/co
so dependency update branches are automatically recognized.
See PR [#442](https://github.com/commit-check/commit-check/pull/442).

## v2.9.0 (2026-06-22)
## v2.9.0 (2026-06-22) { #v290 }

### New Features

Expand All @@ -144,7 +168,7 @@ Full changelog available at [GitHub releases](https://github.com/commit-check/co
`DEFAULT_BRANCH_TYPES` so branches created by AI coding agents are
recognized as valid. See PR [#438](https://github.com/commit-check/commit-check/pull/438).

## v2.8.1 (2026-06-22)
## v2.8.1 (2026-06-22) { #v281 }

### Chores

Expand All @@ -154,7 +178,7 @@ Full changelog available at [GitHub releases](https://github.com/commit-check/co
* Added SchemaStore IDE autocompletion support for `cchk.toml`.
See PR [#433](https://github.com/commit-check/commit-check/pull/433).

## v2.8.0 (2026-06-13)
## v2.8.0 (2026-06-13) { #v280 }

### New Features

Expand All @@ -170,15 +194,15 @@ Full changelog available at [GitHub releases](https://github.com/commit-check/co
`py.typed` marker added for downstream type checkers.
See PR [#424](https://github.com/commit-check/commit-check/pull/424).

## v2.7.1 (2026-06-08)
## v2.7.1 (2026-06-08) { #v271 }

### Chores

* Added `auto` to the list of imperative verbs. See PR [#417](https://github.com/commit-check/commit-check/pull/417).
* Added commit-check vs GitHub Rulesets comparison table to the README.
See PR [#419](https://github.com/commit-check/commit-check/pull/419).

## v2.7.0 (2026-05-16)
## v2.7.0 (2026-05-16) { #v270 }

### New Features

Expand All @@ -203,7 +227,7 @@ Full changelog available at [GitHub releases](https://github.com/commit-check/co
engineering, general), growing the total from 234 to 390.
See PR [#414](https://github.com/commit-check/commit-check/pull/414).

## v2.6.0 (2026-04-20)
## v2.6.0 (2026-04-20) { #v260 }

### New Features

Expand All @@ -214,7 +238,7 @@ Full changelog available at [GitHub releases](https://github.com/commit-check/co

* Fixed `print_error_header` state handling so repeated validations stay consistent when `--compact` is used.

## v2.5.0 (2026-04-03)
## v2.5.0 (2026-04-03) { #v250 }

### New Features

Expand All @@ -226,7 +250,7 @@ Full changelog available at [GitHub releases](https://github.com/commit-check/co

* Fixed incorrect mock target in `test_main_with_message_empty_string_no_stdin_with_git`: was patching `commit_check.util.get_commit_info` (ineffective) instead of `commit_check.engine.get_commit_info`.

## v2.0.0 (2025-10-01)
## v2.0.0 (2025-10-01) { #v200 }

!!! warning

Expand Down Expand Up @@ -262,10 +286,10 @@ Architecture Redesign:

See PR [#280](https://github.com/commit-check/commit-check/pull/280)

## v0.10.2 (2025-08-26)
## v0.10.2 (2025-08-26) { #v0102 }

Last release before the big v2.0 changes.

## v0.1.0 (2022-11-02)
## v0.1.0 (2022-11-02) { #v010 }

Initial release of commit-check.
2 changes: 1 addition & 1 deletion docs/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -188,7 +188,7 @@ The primary use case for CLI arguments is configuring commit-check in `.pre-comm
```yaml
repos:
- repo: https://github.com/commit-check/commit-check
rev: v2.5.0
rev: v2.13.0
hooks:
- id: check-message
args:
Expand Down
8 changes: 4 additions & 4 deletions docs/example.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# Command-line recipes

Ways to invoke the checks directly. For wiring them into a workflow, see the
[pre-commit](guides/pre-commit.md) and [GitHub Actions](guides/github-actions.md)
guides instead — those cover the setup this page assumes you already have.
Ways to invoke the checks directly. For wiring them into a workflow, see
[Integrations](guides/integrations.md) instead — that covers the setup this page
assumes you already have.

Every option, and the environment variable and TOML key that set it, is listed
in [Configuration](configuration.md).
Expand Down Expand Up @@ -104,7 +104,7 @@ pushed:
```yaml title=".pre-commit-config.yaml"
repos:
- repo: https://github.com/commit-check/commit-check
rev: v2.11.0
rev: v2.13.0
hooks:
- id: check-no-force-push
stages: [pre-push]
Expand Down
67 changes: 54 additions & 13 deletions docs/getting-started/quickstart.md → docs/getting-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,16 +1,47 @@
# Quick start
# Getting started

By the end of this page you will have Commit Check rejecting a bad commit
message on your machine, and you will understand what it is telling you.
By the end of this page you will have Commit Check installed, rejecting a bad
commit message on your machine, and wired into the two places it belongs.

It takes about five minutes and needs nothing but a Git repository.

## 1. Install

=== "pip"

```console
$ pip install commit-check
```

=== "uv"

```console
$ uv tool install commit-check
```

=== "pipx"

```console
$ pipx install commit-check
```

Verify the install:

```console
$ pip install commit-check
$ commit-check --version
```

The CLI is also available as `cchk`, which is the same program under a shorter
name.

!!! tip "Supported Python versions"

Commit Check supports Python 3.10 through 3.14, on Linux, macOS and Windows.

Running it as a [pre-commit hook](guides/integrations.md#as-a-pre-commit-hook)
or a [GitHub Action](guides/integrations.md#in-github-actions) needs no
installation step at all — both fetch it for you.

## 2. Watch it reject something

Commit Check works with no configuration at all. Make a deliberately bad commit
Expand Down Expand Up @@ -77,8 +108,8 @@ $ commit-check --branch

`commit-check --message` never evaluates branch rules, and vice versa. Each
check is selected by its own flag, so you can run exactly what a given hook
or CI job needs. The
[rules reference](../rules.md) lists which flag activates each rule.
or CI job needs. The [rules reference](rules.md) lists which flag activates
each rule.

## 5. Write down your policy

Expand Down Expand Up @@ -109,8 +140,8 @@ $ commit-check --message

Even with no config file, Conventional Commits, Conventional Branch, subject
length limits of 5–80 characters, and author name/email patterns are
enforced. Check the *Default* column in the
[rules reference](../rules.md) before assuming a rule is off.
enforced. Check the *Default* column in the [rules reference](rules.md)
before assuming a rule is off.

## 6. Make it automatic

Expand All @@ -126,7 +157,7 @@ belongs:
A pre-commit hook rejects the message as you write it, so nothing bad
reaches the branch in the first place.

[:octicons-arrow-right-24: Pre-commit guide](../guides/pre-commit.md)
[:octicons-arrow-right-24: Pre-commit hook](guides/integrations.md#as-a-pre-commit-hook)

- :material-github:{ .lg .middle } __On every pull request__

Expand All @@ -135,14 +166,24 @@ belongs:
A GitHub Action checks every commit in the PR and can comment on the PR
with what needs fixing.

[:octicons-arrow-right-24: GitHub Actions guide](../guides/github-actions.md)
[:octicons-arrow-right-24: GitHub Actions](guides/integrations.md#in-github-actions)

</div>

## Verifying the download

Releases are built with [SLSA Level 3](https://slsa.dev) provenance. To verify a
release artifact came from this repository's build pipeline:

```console
$ gh attestation verify commit_check-*.whl --repo commit-check/commit-check
```
Comment on lines +178 to +180

@coderabbitai coderabbitai Bot Aug 4, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "== repo files =="
git ls-files | sed -n '1,120p'

echo "== target lines =="
if [ -f docs/getting-started.md ]; then
  nl -ba docs/getting-started.md | sed -n '160,195p'
fi

echo "== attestation occurrences =="
rg -n "gh attestation verify|commit_check-\\*\\.whl" .

echo "== gh attestation CLI help (if installed) =="
if command -v gh >/dev/null 2>&1; then
  gh attestation verify --help | sed -n '1,220p'
else
  echo "gh not installed"
fi

Repository: commit-check/commit-check.com

Length of output: 1132

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "== target lines =="
if [ -f docs/getting-started.md ]; then
  awk 'NR>=155 && NR<=190 { printf "%4d\t%s\n", NR, $0 }' docs/getting-started.md
fi

echo "== attestation occurrences =="
grep -RIn "gh attestation verify\|commit_check-\*\.whl" . || true

echo "== gh attestation CLI help (if installed) =="
if command -v gh >/dev/null 2>&1; then
  gh attestation verify --help | awk 'NR<=240 { print }'
else
  echo "gh not installed"
fi

echo "== static glob expansion probe =="
mkdir -p /tmp/attestation-probe
touch "/tmp/attestation-probe/commit_check-1.0.0-py3-none-any.whl"
touch "/tmp/attestation-probe/commit_check-1.0.0-linux_x86_64.whl"
printf 'sh_args='
(cd /tmp/attestation-probe && sh -c 'set -- commit_check-*.whl; printf "%s\n" "$@"' | awk '{ printf "%s ", "\"" $0 "\""; } END { print "" }')

Repository: commit-check/commit-check.com

Length of output: 10074

Pass one wheel path to gh attestation verify.

The commit_check-*.whl glob expands to multiple arguments when several platform wheels are present, but this command takes one artifact path. Use one exact wheel path or verify each wheel in a loop.

🧰 Tools
🪛 markdownlint-cli2 (0.23.1)

[warning] 178-178: Code block style
Expected: indented; Actual: fenced

(MD046, code-block-style)

[warning] 179-179: Dollar signs used before commands without showing output

(MD014, commands-show-output)

🤖 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 `@docs/getting-started.md` around lines 178 - 180, Update the gh attestation
verify command in the getting-started documentation to pass a single exact wheel
path instead of the commit_check-*.whl glob, or show a loop that verifies each
wheel individually.


## Where to go next

- **[Rules reference](../rules.md)** — every rule, what it does, why it matters,
- **[Rules reference](rules.md)** — every rule, what it does, why it matters,
and how to configure it.
- **[Configuration](../configuration.md)** — every option, its type and default,
- **[Configuration](configuration.md)** — every option, its type and default,
plus the environment variable and CLI flag that override it.
- **[Why Commit Check](why.md)** — the reasoning behind the tool.
- **[Command-line recipes](example.md)** — checking a range, wiring up CI,
reading the JSON output.
Loading