docs: document custom YAML schemes

Author: pboulos

README.md

@@ -141,6 +141,70 @@ refactor!: drop support for Node 6
 
 If no keywords are specified a **Patch** bump is applied.
 
+### Scheme: Custom (YAML)
+
+A user-defined scheme can be supplied via a YAML file using the `--scheme-file` flag. This is
+useful when neither the autotag nor Conventional Commits scheme fits your project's commit
+conventions.
+
+`--scheme-file` is mutually exclusive with an explicitly non-default `--scheme`: pass one or the
+other. Ready-to-copy reference schemes are available under
+[`examples/schemes/`](examples/schemes/).
+
+#### YAML schema
+
+```yaml
+name: my-custom-scheme          # required: identifier used in logs
+description: Optional summary.  # optional: free-form
+
+# Rules are evaluated in declaration order. The first rule whose regex matches
+# the commit message determines the bump. Remaining rules are not consulted.
+rules:
+  - name: breaking-footer       # optional: shown in validation errors
+    match: '(?m)^BREAKING CHANGE:'
+    bump: major
+  - name: feat
+    match: '^feat(\([^)]*\))?:'
+    bump: minor
+  - name: patch-types
+    match: '^(fix|chore|docs|refactor)(\([^)]*\))?:'
+    bump: patch
+
+# Required. What to do when no rule matches a commit.
+# Allowed values: major | minor | patch | none
+default: patch
+```
+
+- `match` is a Go [regexp](https://pkg.go.dev/regexp/syntax) pattern.
+- `bump` and `default` must be one of `major`, `minor`, `patch`, or `none`.
+- A rule with `bump: none` matches the commit but contributes no version change — useful for
+  explicitly ignoring commits (e.g., merge commits) without falling through to the default.
+- `default: none` combined with `--strict-match` will cause unmatched commits to error out instead
+  of being silently ignored.
+
+All validation (regex compilation, allowed bump values, required fields, unknown keys) happens at
+load time, so a malformed scheme fails fast with a clear error before any commits are parsed.
+
+#### Example
+
+Given a scheme file `./my-scheme.yaml`:
+
+```yaml
+name: my-scheme
+rules:
+  - match: '(?m)^BREAKING CHANGE:'
+    bump: major
+  - match: '^feat:'
+    bump: minor
+default: patch
+```
+
+Invoke autotag with:
+
+```sh
+autotag --scheme-file ./my-scheme.yaml
+```
+
 ### Strict Match Option
 
 The `--strict-match` option enforces that commit messages must strictly adhere to the specified commit message scheme.
@@ -164,6 +228,13 @@ When the `--strict-match` option is enabled, the behavior of the commit message
   - With `--strict-match`: Commit messages that do not follow the conventional commit format will result in an
   error, and the commit will not be processed.
 
+- **Custom (YAML) Scheme**:
+  - Without `--strict-match`: Unmatched commits use the scheme's `default` value. When `default:
+  none`, those commits contribute no version change.
+  - With `--strict-match`: Unmatched commits (no rule matches **and** the scheme declares `default:
+  none`) result in an error. If the scheme's `default` is `major`, `minor`, or `patch`, the
+  fallback is always taken and strict-match never fires.
+
 #### Usage
 
 To use the strict match option, add the `--strict-match` flag when running the autotag tool:

examples/schemes/autotag.yaml

@@ -0,0 +1,20 @@
+# Reproduces the built-in "autotag" scheme as a --scheme-file.
+# Use this as a starting point when customizing the bracket/hash keyword style.
+name: autotag
+description: Bump based on [major]/[minor]/[patch] or #major/#minor/#patch markers.
+
+rules:
+  - name: major
+    match: '(?i)\[major\]|#major'
+    bump: major
+  - name: minor
+    match: '(?i)\[minor\]|#minor'
+    bump: minor
+  - name: patch
+    match: '(?i)\[patch\]|#patch'
+    bump: patch
+
+# The built-in autotag scheme falls back to a patch bump when no marker is
+# present. Use `default: none` if you'd rather unmatched commits contribute
+# nothing (combine with --strict-match to turn them into errors).
+default: patch

examples/schemes/conventional.yaml

@@ -0,0 +1,32 @@
+# Reproduces the built-in "conventional" scheme (in non-strict mode) as a
+# --scheme-file. Use this as a starting point when customizing which commit
+# types bump which version segment.
+name: conventional
+description: Conventional Commits v1.0.0 — https://www.conventionalcommits.org/en/v1.0.0/
+
+rules:
+  # A footer starting with "BREAKING CHANGE:" anywhere in the commit body
+  # forces a major bump, even when the header type is unknown.
+  - name: breaking-footer
+    match: '(?m)^BREAKING CHANGE:'
+    bump: major
+
+  # A trailing '!' after the type or type(scope) also marks a breaking change.
+  - name: breaking-bang
+    match: '^\w+(\([^)]*\))?!:'
+    bump: major
+
+  # A new feature — minor bump.
+  - name: feat
+    match: '^feat(\([^)]*\))?:'
+    bump: minor
+
+  # The remaining well-known types all map to a patch bump.
+  - name: patch-types
+    match: '^(fix|build|chore|ci|docs|perf|refactor|revert|style|test)(\([^)]*\))?:'
+    bump: patch
+
+# Commits that don't match any rule contribute no version change. This matches
+# the built-in conventional scheme's behavior: non-conforming commits are
+# silently ignored unless --strict-match is enabled, in which case they error.
+default: none