feat: commit message check can be opted out

- no (or an empty) [commit.types] in afterpython.toml means no check, instead of blocking every commit
- ap init asks whether to check commit messages; if not, [commit.types] is written commented out

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: softwareentrepreneer

afterpython/doc/package_maintenance/commit_workflow.md

@@ -45,6 +45,11 @@ wip = "Work in progress"
 ```
 To allow a new type, add a line, e.g. `deps = "Dependency updates"`; to disallow one, remove its line. The descriptions are shown in the commit message template and in the error message when a commit is rejected.
 
+:::{note} Opting out
+Commit messages are only checked when `[commit.types]` has at least one type.
+To opt out, remove the section or leave it empty. If you opted out during `ap init`, the section is commented out, uncomment it to opt in.
+:::
+
 ### Bypassing Checks
 - `SKIP=ap-commit git commit` — skip the commit message check
 - `git commit --no-verify` — skip all pre-commit and commit message hooks

src/afterpython/cli/commands/commit_msg.py

@@ -67,7 +67,10 @@ def _subject(message: str) -> str:
 )
 @click.pass_context
 def commit_msg(ctx, message_file: Path, template: bool):
-    """Check a commit message against [commit.types] in afterpython.toml (used by the ap-commit hook)"""
+    """Check a commit message against [commit.types] in afterpython.toml (used by the ap-commit hook)
+
+    Without (or with an empty) [commit.types], any message is accepted.
+    """
     from afterpython._io.toml import _from_tomlkit
     from afterpython.tools._afterpython import read_afterpython
 
@@ -81,12 +84,9 @@ def commit_msg(ctx, message_file: Path, template: bool):
             _add_template(message_file, commit_types)
         return
 
+    # opted out: no (or an empty) [commit.types] section means no check
     if not commit_types:
-        click.echo(
-            "❌ No commit types found, add a [commit.types] section to afterpython/afterpython.toml",
-            err=True,
-        )
-        ctx.exit(1)
+        return
 
     subject = _subject(message_file.read_text(encoding="utf-8"))
     # empty messages are rejected by git itself

src/afterpython/cli/commands/init.py

@@ -142,7 +142,17 @@ def init(ctx, yes, skip_website: bool):
 
         init_pyproject()
 
-        init_afterpython()
+        # only asked when afterpython.toml is created, it's ignored otherwise
+        commit_types = (
+            yes
+            or (afterpython_path / "afterpython.toml").exists()
+            or click.confirm(
+                "\nCheck commit messages against conventional commit types "
+                "(e.g. 'feat: add X', types listed in afterpython.toml)?",
+                default=True,
+            )
+        )
+        init_afterpython(commit_types=commit_types)
 
         if not skip_website:
             # check=True so a failure inside `ap init website` aborts the parent

src/afterpython/tools/_afterpython.py

@@ -106,12 +106,37 @@ def update_afterpython(data_update: dict):
     write_toml(afterpython_toml_path, existing_data)
 
 
-def init_afterpython():
-    """Initialize afterpython.toml"""
+def _comment_out_commit_types(text: str) -> str:
+    """Comment out the [commit.types] section, so the ap-commit hook doesn't check commit messages"""
+    lines = text.splitlines()
+    start = lines.index("[commit.types]")
+    end = next(
+        (i for i in range(start + 1, len(lines)) if lines[i].startswith("[")),
+        len(lines),
+    )
+    lines[start:end] = [
+        "# uncomment to check commit messages against these types",
+        *(f"# {line}" if line.strip() else line for line in lines[start:end]),
+    ]
+    return "\n".join(lines) + "\n"
+
+
+def init_afterpython(commit_types: bool = True):
+    """Initialize afterpython.toml
+
+    Args:
+        commit_types: if False, [commit.types] is commented out (commit messages are not checked)
+    """
     afterpython_toml_path = ap.paths.afterpython_path / "afterpython.toml"
     if afterpython_toml_path.exists():
         print(f"afterpython.toml already exists at {afterpython_toml_path}")
         return
     afterpython_template_path = ap.paths.templates_path / "afterpython-template.toml"
-    shutil.copy(afterpython_template_path, afterpython_toml_path)
+    if commit_types:
+        shutil.copy(afterpython_template_path, afterpython_toml_path)
+    else:
+        text = afterpython_template_path.read_text(encoding="utf-8")
+        afterpython_toml_path.write_text(
+            _comment_out_commit_types(text), encoding="utf-8"
+        )
     print(f"Created {afterpython_toml_path}")

tests/test_commit_msg.py

@@ -76,16 +76,17 @@ def test_error_lists_allowed_types(tmp_path):
         assert t in result.output and desc in result.output
 
 
-def test_missing_commit_types(tmp_path, monkeypatch):
+@pytest.mark.parametrize("toml", ["", "[commit.types]\n"])
+def test_no_commit_types_skips_check(tmp_path, monkeypatch, toml):
     import tomlkit
 
     monkeypatch.setattr(
         "afterpython.tools._afterpython.read_afterpython",
-        lambda: tomlkit.document(),
+        lambda: tomlkit.parse(toml),
     )
-    result = run(tmp_path, "feat: add X")
-    assert result.exit_code == 1
-    assert "[commit.types]" in result.output
+    result = run(tmp_path, "anything goes")
+    assert result.exit_code == 0, result.output
+    assert result.output == ""
 
 
 GIT_DEFAULT_MESSAGE = (