From bf00f79b29628abd07dd3eb1cd3d5d62e631acb5 Mon Sep 17 00:00:00 2001
From: shenxianpeng <xianpeng.shen@gmail.com>
Date: Sat, 1 Aug 2026 23:49:14 +0300
Subject: [PATCH] docs: clarify allow_branch_types defaults are a superset of
 the spec

Addresses the review comment on #505: the options table now lists the full
default (all 21 types including AI agent and bot prefixes) and the docs
explicitly note that DEFAULT_BRANCH_TYPES is a superset of the Conventional
Branch spec, with strict spec-only validation available via an explicit
allow_branch_types setting.

Closes #494
---
 README.md              |  4 ++++
 docs/configuration.rst | 25 ++++++++++++++++++++++---
 2 files changed, 26 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 7ebbf906..c1cff445 100644
--- a/README.md
+++ b/README.md
@@ -127,6 +127,10 @@ ai_attribution = "forbid"
 [branch]
 # https://conventionalbranch.org
 conventional_branch = true
+# Optional: the defaults are a superset of the Conventional Branch spec — spec
+# types plus Conventional Commit types (build, ci, docs, perf, refactor, style,
+# test) and AI/bot prefixes (ai, claude, codex, copilot, cursor, dependabot,
+# renovate), see docs/configuration.rst. Omit this option to use the defaults.
 allow_branch_types = [
     "feature",
     "bugfix",
diff --git a/docs/configuration.rst b/docs/configuration.rst
index 4b1495f2..0c658df9 100644
--- a/docs/configuration.rst
+++ b/docs/configuration.rst
@@ -135,7 +135,26 @@ Example Configuration
     [branch]
     # https://conventionalbranch.org
     conventional_branch = true
-    allow_branch_types = ["feature", "bugfix", "hotfix", "release", "chore", "feat", "fix", "build", "ci", "docs", "perf", "refactor", "test", "style"]
+    # Optional: defaults are a superset of the Conventional Branch spec — the
+    # spec types plus Conventional Commit types, AI agent prefixes and bot
+    # prefixes (see the Options table below for the full list). Omit this
+    # option to use the defaults, or set your own list for a strict subset.
+    allow_branch_types = [
+        "feature",
+        "bugfix",
+        "hotfix",
+        "release",
+        "chore",
+        "feat",
+        "fix",
+        "build",
+        "ci",
+        "docs",
+        "perf",
+        "refactor",
+        "style",
+        "test",
+    ]
     # allow_branch_names = []  # Optional - additional standalone branch names (e.g., ["develop", "staging"])
     # require_rebase_target = "main"  # Optional - no rebase requirement by default
     # ignore_authors = []      # Optional - no authors ignored by default
@@ -433,8 +452,8 @@ Options Table Description
    * - branch
      - allow_branch_types
      - list[str]
-     - ["feature", "bugfix", "hotfix", "release", "chore", "feat", "fix", "build", "ci", "docs", "perf", "refactor", "test", "style"]
-     - Allowed branch types when conventional_branch is true. AI agent prefixes (``ai/``, ``claude/``, ``codex/``, ``copilot/``, ``cursor/``) and bot prefixes (``dependabot/``) are also included by default.
+     - ["feature", "bugfix", "hotfix", "release", "chore", "feat", "fix", "build", "ci", "docs", "perf", "refactor", "style", "test", "ai", "claude", "codex", "copilot", "cursor", "dependabot", "renovate"]
+     - Allowed branch types when ``conventional_branch`` is true. The default is a superset of the `Conventional Branch spec <https://conventionalbranch.org/>`_: the spec types (``feature``, ``bugfix``, ``hotfix``, ``release``, ``chore``) plus the Conventional Commit types (``build``, ``ci``, ``docs``, ``perf``, ``refactor``, ``style``, ``test``), AI agent prefixes (``ai``, ``claude``, ``codex``, ``copilot``, ``cursor``) and bot prefixes (``dependabot``, ``renovate``). For strict spec-only validation, set this option explicitly (e.g. ``["feature", "bugfix", "hotfix", "release", "chore"]``).
    * - branch
      - allow_branch_names
      - list[str]