diff --git a/docs/changelog.md b/docs/changelog.md index 2f962d6..f271cf8 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -11,6 +11,7 @@ page that documents it. | Version | What changed | Documented in | |---|---|---| +| [2.21.0](#v2210) | A pull request description must tick one of its template's AI declaration checkboxes (opt-in) | [CC501](rules.md#cc501) · [Requiring the template's AI declaration](guides/policies.md#requiring-the-templates-ai-declaration) | | [2.20.5](#v2205) | The author checks cover a repository's first commit; a run takes about half the time to start; releases on PyPI carry provenance | [Checking the committer](example.md#checking-the-committer) · [CC017](rules.md#cc017) | | [2.20.3](#v2203) | Failures print a one-line header and an indented block per check, in place of the ASCII banner; an agent skill for coding agents | [Getting started](getting-started.md#2-watch-it-reject-something) · [With AI coding agents](guides/ai-agents.md#tell-the-agent) | | [2.20.1](#v2201) | `--ai-attribution-only` checks a pull request description against your AI policy; JSON lists the AI tools found; more AI marks recognised | [Checking a pull request description](guides/policies.md#checking-a-pull-request-description) · [CC013](rules.md#cc013) | @@ -40,6 +41,16 @@ page that documents it. | [2.5.0](#v250) | Organization-wide config with `inherit_from` | [Across an organization](guides/organization.md) | | [2.0.0](#v200) | Configuration moved from YAML to TOML — breaking | [Migrating from v1](migration.md) | +## v2.21.0 (2026-11-16) { #v2210 } + +### Added + +* CC501 checks that a pull request description ticks exactly one of the AI declaration checkboxes listed in `[pull_request] ai_declaration_checkboxes`. ([CC501](rules.md#cc501), [#699](https://github.com/commit-check/commit-check/pull/699)) + +### Fixed + +* CC014's advice names the trailer to add when the message has no blank line before the AI mark. ([CC014](rules.md#cc014), [#696](https://github.com/commit-check/commit-check/pull/696)) + ## v2.20.5 (2026-11-11) { #v2205 } ### Changed diff --git a/docs/compare/tools.md b/docs/compare/tools.md index 7283238..1bc6b10 100644 --- a/docs/compare/tools.md +++ b/docs/compare/tools.md @@ -65,7 +65,7 @@ Replace the hook: ```yaml title=".pre-commit-config.yaml" repos: - repo: https://github.com/commit-check/commit-check - rev: v2.20.5 + rev: v2.21.0 hooks: - id: check-message ``` diff --git a/docs/configuration.md b/docs/configuration.md index f5a41c6..c1781d7 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -87,10 +87,10 @@ $ echo "feat: add streaming support" | commit-check -m ``` It is a warning, not an error: the exit code and the JSON on stdout do not -change. The top-level `warn` list and the GitHub App's +change. The top-level `warn` list and the [`[jira]`](guides/github-app.md#jira-ticket-references) and [`[pull_request]`](#pull-requests-every-commit-or-the-squash-message) sections -are read elsewhere and are not reported. The Python API reads no file at all +are not checked for unknown settings. The Python API reads no file at all (it takes a `config` dict), and the MCP server loads the file itself without reporting unknown settings. @@ -274,7 +274,7 @@ Used from a hook definition, with no config file anywhere in the repository: ```yaml title=".pre-commit-config.yaml" repos: - repo: https://github.com/commit-check/commit-check - rev: v2.20.5 + rev: v2.21.0 hooks: - id: check-message args: @@ -415,3 +415,4 @@ the same thing twice, so read the description rather than the cell: | files | prohibited_patterns | list[str] | [] (empty list) | fnmatch patterns a committed path may not match, e.g. `["*.pem", ".env", "id_rsa*"]`. A bare pattern also matches the file name at any depth. Matching is case-sensitive on every platform, like git pathspecs. Empty disables the rule. | | files | max_path_length | int | 0 (disabled) | Longest a committed file path may be, in characters. `0` disables the rule. | | pull_request | check | str | "commits" | GitHub App only. `"commits"` checks every commit of a pull request on its own; `"squash"` checks the one message a squash merge would land, built from the repository's merge settings. See [Pull requests](#pull-requests-every-commit-or-the-squash-message). | +| pull_request | ai_declaration_checkboxes | list[str] | [] (rule off) | The texts of the AI declaration boxes in the pull request template, one per box. When set, a pull request description checked with `--ai-attribution-only` must tick exactly one of them; see [CC501](rules.md#cc501). Read by the CLI, the Action and the App. | diff --git a/docs/example.md b/docs/example.md index ab42c0d..e55c8bc 100644 --- a/docs/example.md +++ b/docs/example.md @@ -169,7 +169,7 @@ pushed: ```yaml title=".pre-commit-config.yaml" repos: - repo: https://github.com/commit-check/commit-check - rev: v2.20.5 + rev: v2.21.0 hooks: - id: check-no-force-push stages: [pre-push] diff --git a/docs/guides/github-app.md b/docs/guides/github-app.md index f0fdfa3..303afc9 100644 --- a/docs/guides/github-app.md +++ b/docs/guides/github-app.md @@ -104,7 +104,8 @@ push or pull request, in the same four places: `cchk.toml`, `commit-check.toml`, applies, precedence included; the `[push]`, `[files]` and `[tag]` sections are read but have nothing to act on here. Nothing is App-specific to set apart from `[pull_request]` (above) and `[jira]` (below); the CLI and the Action ignore -them. +them, except `[pull_request] ai_declaration_checkboxes` +([CC501](../rules.md#cc501)), which all three read. [`inherit_from`](organization.md) works, and a `github:` target is fetched with the App's own credentials, so a shared config in a private `.github` repository diff --git a/docs/guides/policies.md b/docs/guides/policies.md index 94f7f9b..802b6e4 100644 --- a/docs/guides/policies.md +++ b/docs/guides/policies.md @@ -228,6 +228,42 @@ $ gh pr view 42 --json body -q .body | commit-check --ai-attribution-only --form ["Devin"] ``` +### Requiring the template's AI declaration + +Many pull request templates ask the author to tick one of two boxes, such as +"No AI tools were used" or "If AI tools were used, I have disclosed which +ones". Django, statsmodels and Frigate each run their own script in CI to make +sure one of them is ticked. List the boxes' texts and +[CC501](../rules.md#cc501) does that check: + +```toml title="cchk.toml" +[pull_request] +ai_declaration_checkboxes = ["No AI tools were used", "If AI tools were used"] +``` + +```console +$ gh pr view 42 --json body -q .body | commit-check --ai-attribution-only +✖ Commit rejected by Commit Check · 1 check failed + +✖ CC501 ai-declaration failed: - [ ] **No AI tools were used** in preparing this PR. (+1 more line) + No AI declaration box is ticked + Suggest: Tick the box that applies: "No AI tools were used" or "If AI tools were used" + Docs: https://commit-check.com/rules/#cc501 +``` + +Each option is the start of a box's text, so `**If AI tools were used**, I +have disclosed which ones.` matches `If AI tools were used`. The rule fails +when no box is ticked, when both are, and when the description has no boxes +at all. Boxes inside an HTML comment are ignored, so instructions in the +template do not count as an answer. + +It works on its own: `ai_attribution` can stay at `"ignore"`. In the +[Action](github-actions.md), turn on `pr-body-ai-attribution: true`; in the +[GitHub App](github-app.md), set `body_ai_attribution = true` under +`[pull_request]`. The App checks the description again whenever it is +edited; the Action does too once its workflow lists `edited` under +`pull_request` `types`. + ### Asking for disclosure instead Most projects that allow AI assistance ask to be told about it. diff --git a/docs/guides/pre-commit.md b/docs/guides/pre-commit.md index 8f9c1fb..c00ca29 100644 --- a/docs/guides/pre-commit.md +++ b/docs/guides/pre-commit.md @@ -8,7 +8,7 @@ Add Commit Check to `.pre-commit-config.yaml`: ```yaml title=".pre-commit-config.yaml" repos: - repo: https://github.com/commit-check/commit-check - rev: v2.20.5 + rev: v2.21.0 hooks: - id: check-message - id: check-branch @@ -68,7 +68,7 @@ Options can be passed as hook arguments, which keeps everything in one file: ```yaml title=".pre-commit-config.yaml" repos: - repo: https://github.com/commit-check/commit-check - rev: v2.20.5 + rev: v2.21.0 hooks: - id: check-message args: @@ -90,7 +90,7 @@ colon, and lets the commit through: ```yaml title=".pre-commit-config.yaml" repos: - repo: https://github.com/commit-check/commit-check - rev: v2.20.5 + rev: v2.21.0 hooks: - id: check-message args: [--fix] diff --git a/docs/rules.md b/docs/rules.md index 82c9def..fdc50d4 100644 --- a/docs/rules.md +++ b/docs/rules.md @@ -1141,3 +1141,75 @@ git tag v1.2.3-rc.1 * `tag.regex` — the pattern a tag name must match. An empty value disables the pattern match. + +## Pull request rules + +### ai-declaration (CC501) { #cc501 } + +**What it does** + +Checks that a pull request description answers the AI question its template +asks, often under an "AI disclosure" heading: exactly one of the boxes listed in +`pull_request.ai_declaration_checkboxes` is ticked. It runs only under `--ai-attribution-only`, the mode that reads a +pull request description, and only when that option is set. + +A box is a task-list item (`- [ ]`, `* [x]`, `1. [X]`) whose text starts with +one of the options, compared without case, emphasis or extra spaces, on whole +words. `- [ ] **No AI tools were used** in preparing this PR.` is a box for +the option `No AI tools were used`. Boxes inside HTML comments or code blocks +are not read, so the template's own instructions never count as an answer. +When two options both fit a box, the longer one wins. + +The rule fails when: + +* no box is ticked, +* more than one option is ticked, or +* the description has no box at all, as when the template was deleted. + +Authors in `commit.ignore_authors` are skipped, so a bot's pull request does +not need the declaration. + +**Why is this bad?** + +A project that asks contributors to declare AI use can only rely on the answer +if it is there. An unticked box reads the same as "I did not look", and a +deleted template the same as a missing answer. Projects that ask the question +end up checking the description in CI, each with its own script. + +**Example** + +```toml title="cchk.toml" +[pull_request] +ai_declaration_checkboxes = ["No AI tools were used", "If AI tools were used"] +``` + +```markdown +#### AI Assistance Disclosure (REQUIRED) +- [ ] **No AI tools were used** in preparing this PR. +- [ ] **If AI tools were used**, I have disclosed which ones. +``` + +```console +$ gh pr view 42 --json body -q .body | commit-check --ai-attribution-only +✖ Commit rejected by Commit Check · 1 check failed + +✖ CC501 ai-declaration failed: - [ ] **No AI tools were used** in preparing this PR. (+1 more line) + No AI declaration box is ticked + Suggest: Tick the box that applies: "No AI tools were used" or "If AI tools were used" + Docs: https://commit-check.com/rules/#cc501 +``` + +Use instead: + +```markdown +- [x] **No AI tools were used** in preparing this PR. +- [ ] **If AI tools were used**, I have disclosed which ones. +``` + +**Options** + +* `pull_request.ai_declaration_checkboxes` — the text each box starts with, one + string per box. Unset (the default) turns the rule off. The + [Action](guides/github-actions.md) runs it with `pr-body-ai-attribution: true` + and the [GitHub App](guides/github-app.md) with + `[pull_request] body_ai_attribution = true`.