Skip to content

Commit c41bd6e

Browse files
shenxianpengshenxianpeng
committed
feat: add policy presets and adoption kit
Add three ready-to-use policy presets (Minimal, Recommended, Strict) so users don't have to guess among 20+ config options: - presets/minimal.toml — personal/solo projects - presets/recommended.toml — open source projects - presets/strict.toml — enterprise/regulated teams Add docs/presets.rst with a side-by-side comparison, quick-start guide, override examples, offline usage, and FAQ. Wire presets into README, docs/index.rst, and docs/configuration.rst.
1 parent 4b0e6ae commit c41bd6e

7 files changed

Lines changed: 429 additions & 1 deletion

File tree

‎README.rst‎

Lines changed: 27 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -98,18 +98,44 @@ Or install directly from the GitHub repository:
9898
pip install git+https://github.com/commit-check/commit-check.git@main
9999
100100
Then, run ``commit-check --help`` or ``cchk --help`` (alias for ``commit-check``) from the command line.
101-
For more information, see the `docs <https://commit-check.github.io/commit-check/cli_args.html>`_.
101+
For more information, see the `documentation <https://commit-check.github.io/commit-check/>`_.
102102

103103

104104
Configuration
105105
-------------
106106

107+
.. tip::
108+
109+
**New: Policy Presets — don't guess, pick a preset.** If you don't want to
110+
wade through 20+ config options, start with one of three presets:
111+
112+
- ``presets/minimal.toml`` — personal / solo projects
113+
- ``presets/recommended.toml`` — open source projects
114+
- ``presets/strict.toml`` — enterprise / regulated teams
115+
116+
See the :doc:`Policy Presets & Adoption Kit <docs/presets>` for a side-by-side
117+
comparison and one-liner setup.
118+
107119
Commit Check can be configured in three ways (in order of priority):
108120

109121
1. **Command-line arguments** — Override settings for specific runs
110122
2. **Environment variables** — Configure via ``CCHK_*`` environment variables
111123
3. **Configuration files** — Use ``cchk.toml`` or ``commit-check.toml``
112124

125+
Use a Policy Preset (Recommended)
126+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
127+
128+
Create a ``.github/cchk.toml`` with a single ``inherit_from`` line:
129+
130+
.. code-block:: toml
131+
132+
# .github/cchk.toml
133+
inherit_from = "github:commit-check/commit-check:presets/recommended.toml"
134+
135+
That's it. The preset configures everything for you. You can always add
136+
local overrides below the ``inherit_from`` line. See :doc:`Policy Presets &
137+
Adoption Kit <docs/presets>` for the full comparison.
138+
113139
Use Default Configuration
114140
~~~~~~~~~~~~~~~~~~~~~~~~~
115141

‎docs/configuration.rst‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,11 @@
11
Configuration
22
=============
33

4+
.. tip::
5+
6+
**New to commit-check?** Start with a :doc:`Policy Preset <presets>` instead.
7+
Pick Minimal, Recommended, or Strict — one line gets you going.
8+
49
``commit-check`` can be configured in three ways with the following priority (highest to lowest):
510

611
1. **Command-line arguments** (``--subject-imperative=true``)

‎docs/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@
44
:hidden:
55

66
self
7+
presets
78
what-is-new
89
configuration
910
example

‎docs/presets.rst‎

Lines changed: 288 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,288 @@
1+
Policy Presets & Adoption Kit
2+
============================
3+
4+
**Don't guess. Pick a preset.**
5+
6+
Commit Check exposes over 20 configuration options. Instead of wading through
7+
every toggle, start with one of three presets designed for different use cases.
8+
Each preset is a ready-to-use ``cchk.toml`` fragment that you can inherit with
9+
a single line. You can always add local overrides on top.
10+
11+
.. contents:: Table of Contents
12+
:depth: 2
13+
:local:
14+
:backlinks: none
15+
16+
17+
Choose Your Preset
18+
------------------
19+
20+
.. list-table::
21+
:header-rows: 1
22+
:widths: 25 25 25 25
23+
24+
* - Use case
25+
- Preset
26+
- What it enforces
27+
- One-liner
28+
* - | 🧑‍💻 **Personal / solo project**
29+
| You work alone, want basic consistency
30+
| without slowing you down.
31+
- **Minimal**
32+
- | ✅ Conventional Commits
33+
| ✅ Conventional Branch
34+
| ❌ Everything else relaxed
35+
- .. code-block:: toml
36+
37+
inherit_from = "github:commit-check/commit-check:presets/minimal.toml"
38+
* - | 📦 **Open source project**
39+
| You maintain a library or tool with
40+
| external contributors. Want review-friendly
41+
| history without over-engineering.
42+
- **Recommended**
43+
- | ✅ Conventional Commits
44+
| ✅ Imperative mood
45+
| ✅ Subject length limits
46+
| ✅ Conventional Branch
47+
| ✅ Blocks force pushes
48+
| ✅ Blocks WIP commits
49+
| ❌ Capitalization not required
50+
| ❌ No sign-off required
51+
- .. code-block:: toml
52+
53+
inherit_from = "github:commit-check/commit-check:presets/recommended.toml"
54+
* - | 🏢 **Enterprise / regulated**
55+
| You work in a team that demands
56+
| full traceability, sign-off, and
57+
| clean audit trails.
58+
- **Strict**
59+
- | ✅ Conventional Commits
60+
| ✅ Imperative mood
61+
| ✅ Capitalized subjects
62+
| ✅ Subject length (10–72)
63+
| ✅ Conventional Branch
64+
| ✅ Blocks force pushes
65+
| ✅ Blocks WIP / empty / fixup
66+
| ✅ Requires commit body
67+
| ✅ Requires Signed-off-by
68+
| ✅ Requires rebase onto main
69+
- .. code-block:: toml
70+
71+
inherit_from = "github:commit-check/commit-check:presets/strict.toml"
72+
73+
74+
Quick Start: 30 Seconds to Configure
75+
-------------------------------------
76+
77+
**Step 1 — Pick your preset:**
78+
79+
+---------------------------+-----------------------------------------------+
80+
| Your situation | Use this |
81+
+===========================+===============================================+
82+
| I work alone | ``presets/minimal.toml`` |
83+
+---------------------------+-----------------------------------------------+
84+
| I run an open source repo | ``presets/recommended.toml`` |
85+
+---------------------------+-----------------------------------------------+
86+
| I work in a company team | ``presets/strict.toml`` |
87+
+---------------------------+-----------------------------------------------+
88+
89+
**Step 2 — Create your config file** (choose one location):
90+
91+
.. code-block:: toml
92+
:caption: .github/cchk.toml (recommended — keeps root clean)
93+
94+
inherit_from = "github:commit-check/commit-check:presets/recommended.toml"
95+
96+
# Optional: add local overrides below
97+
[commit]
98+
subject_max_length = 72
99+
100+
.. code-block:: toml
101+
:caption: cchk.toml (root directory)
102+
103+
inherit_from = "github:commit-check/commit-check:presets/recommended.toml"
104+
105+
**Step 3 — Done.** ``commit-check`` picks up the preset automatically. No
106+
need to copy-paste 20 options.
107+
108+
You can also pin to a specific version tag for stability:
109+
110+
.. code-block:: toml
111+
112+
inherit_from = "github:commit-check/commit-check@v2.6.0:presets/recommended.toml"
113+
114+
115+
What Each Preset Checks (Side-by-Side)
116+
--------------------------------------
117+
118+
.. list-table::
119+
:header-rows: 1
120+
:widths: 25 15 17 17 26
121+
122+
* - Check
123+
- Minimal
124+
- Recommended
125+
- Strict
126+
- Notes
127+
* - Conventional Commits
128+
- ✅
129+
- ✅
130+
- ✅
131+
- All presets require ``type(scope): description``
132+
* - Subject capitalized
133+
- ❌
134+
- ❌
135+
- ✅
136+
- ``Feat: ...`` (capital F)
137+
* - Subject imperative
138+
- ❌
139+
- ✅
140+
- ✅
141+
- ``fix`` not ``fixed``
142+
* - Max subject length
143+
- ❌
144+
- 80
145+
- 72
146+
- Characters (GitHub truncates at 72 in log)
147+
* - Min subject length
148+
- ❌
149+
- 5
150+
- 10
151+
- Characters
152+
* - Allowed commit types
153+
- 10 types
154+
- 10 types
155+
- 10 types
156+
- feat, fix, docs, style, refactor, test, chore, perf, build, ci
157+
* - Merge commits
158+
- ✅ allowed
159+
- ✅ allowed
160+
- ✅ allowed
161+
-
162+
* - Revert commits
163+
- ✅ allowed
164+
- ✅ allowed
165+
- ✅ allowed
166+
-
167+
* - Empty commits
168+
- ✅ allowed
169+
- ❌ blocked
170+
- ❌ blocked
171+
-
172+
* - Fixup commits
173+
- ✅ allowed
174+
- ✅ allowed
175+
- ❌ blocked
176+
- ``fixup! ...`` / ``squash! ...``
177+
* - WIP commits
178+
- ✅ allowed
179+
- ❌ blocked
180+
- ❌ blocked
181+
- ``WIP: ...`` / ``wip: ...``
182+
* - Require body
183+
- ❌
184+
- ❌
185+
- ✅
186+
-
187+
* - Require Signed-off-by
188+
- ❌
189+
- ❌
190+
- ✅
191+
- DCO-style sign-off
192+
* - Conventional Branch
193+
- ✅
194+
- ✅
195+
- ✅
196+
- ``<type>/<description>``
197+
* - Allowed branch types
198+
- 7 types
199+
- 7 types
200+
- 5 types
201+
- Strict removes ``feat``, ``fix``
202+
* - Require rebase
203+
- ❌
204+
- ❌
205+
- ✅ onto main
206+
- Branch must be rebased onto ``main``
207+
* - Block force push
208+
- ❌
209+
- ✅
210+
- ✅
211+
- ``git push --force`` rejected
212+
213+
214+
Overriding and Extending Presets
215+
--------------------------------
216+
217+
Presets use ``inherit_from``, so you can override any option in your local
218+
config file. Local settings always take priority:
219+
220+
.. code-block:: toml
221+
:caption: .github/cchk.toml
222+
223+
inherit_from = "github:commit-check/commit-check:presets/recommended.toml"
224+
225+
[commit]
226+
# Override: our team prefers capitalized subjects
227+
subject_capitalized = true
228+
# Override: allow additional commit types used by our tooling
229+
allow_commit_types = ["feat", "fix", "docs", "style", "refactor", "test", "chore", "perf", "build", "ci", "infra", "deps"]
230+
231+
[branch]
232+
# Override: add custom branch names
233+
allow_branch_names = ["develop", "staging"]
234+
235+
236+
Using a Local Copy (Air-Gapped / Offline)
237+
-----------------------------------------
238+
239+
If you prefer not to fetch from GitHub at runtime, copy the preset file
240+
directly into your repository and use a local path:
241+
242+
.. code-block:: bash
243+
244+
# Download the preset once
245+
curl -o .github/cchk.toml \
246+
https://raw.githubusercontent.com/commit-check/commit-check/main/presets/recommended.toml
247+
248+
Then edit ``.github/cchk.toml`` directly to add overrides (no ``inherit_from``
249+
needed — you're editing the file itself).
250+
251+
Alternatively, point ``inherit_from`` at a local relative path:
252+
253+
.. code-block:: toml
254+
255+
inherit_from = "../shared-org-config/presets/strict.toml"
256+
257+
258+
FAQ
259+
---
260+
261+
**Q: Can I switch presets later?**
262+
263+
Yes. Just change the ``inherit_from`` line. Existing commit history is
264+
unaffected — only future commits are validated.
265+
266+
**Q: What if I need a mix of Recommended and Strict?**
267+
268+
Start with ``recommended.toml`` and add the Strict options you want as local
269+
overrides (e.g., ``require_signed_off_by = true``). You don't need to pick
270+
one preset exactly.
271+
272+
**Q: Do presets work in CI / pre-commit / GitHub Actions?**
273+
274+
Yes. All enforcement points read the same ``cchk.toml``, so the preset applies
275+
everywhere automatically.
276+
277+
**Q: Are presets versioned?**
278+
279+
Yes — pin to a tag for stability:
280+
281+
.. code-block:: toml
282+
283+
inherit_from = "github:commit-check/commit-check@v2.6.0:presets/recommended.toml"
284+
285+
**Q: What happens to my old custom config?**
286+
287+
Nothing breaks. Presets are opt-in. If you already have a ``cchk.toml``
288+
without ``inherit_from``, it keeps working as before.

‎presets/minimal.toml‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# Minimal Policy Preset — for personal / solo projects
2+
#
3+
# What it checks:
4+
# - Commit messages follow Conventional Commits format
5+
# - Branch names follow Conventional Branch format
6+
#
7+
# What it does NOT enforce:
8+
# - No imperative mood or capitalization requirements
9+
# - No subject length limits
10+
# - All commit flavors allowed (merge, revert, fixup, WIP, empty)
11+
# - Force pushes allowed
12+
# - No sign-off or body requirements
13+
#
14+
# Use this when: you work alone, want basic consistency without friction.
15+
#
16+
# Usage:
17+
# inherit_from = "github:commit-check/commit-check:presets/minimal.toml"
18+
19+
[commit]
20+
conventional_commits = true
21+
subject_capitalized = false
22+
subject_imperative = false
23+
# No subject_max_length / subject_min_length — no limits
24+
allow_commit_types = ["feat", "fix", "docs", "style", "refactor", "test", "chore", "perf", "build", "ci"]
25+
allow_merge_commits = true
26+
allow_revert_commits = true
27+
allow_empty_commits = true
28+
allow_fixup_commits = true
29+
allow_wip_commits = true
30+
require_body = false
31+
require_signed_off_by = false
32+
33+
[branch]
34+
conventional_branch = true
35+
allow_branch_types = ["feature", "bugfix", "hotfix", "release", "chore", "feat", "fix"]
36+
37+
[push]
38+
allow_force_push = true

0 commit comments

Comments
 (0)