Skip to content
Permalink

Comparing changes

Choose two branches to see what’s changed or to start a new pull request. If you need to, you can also or learn more about diff comparisons.

Open a pull request

Create a new pull request by comparing changes across two branches. If you need to, you can also . Learn more about diff comparisons here.
base repository: commitizen-tools/commitizen
Failed to load repositories. Confirm that selected base ref is valid, then try again.
Loading
base: master
Choose a base ref
...
head repository: commitizen-tools/commitizen
Failed to load repositories. Confirm that selected head ref is valid, then try again.
Loading
compare: docs/agent-playbooks
Choose a head ref
Checking mergeability… Don’t worry, you can still create the pull request.
  • 8 commits
  • 12 files changed
  • 2 contributors

Commits on May 30, 2026

  1. docs(contributing): add architecture overview 

    A general-audience map of Commitizen's subsystems (cli, commands, config, providers, changelog_formats, version_schemes, plugins) and how they wire together. Pairs with the existing contributor guide and is also the anchor for the new agent-facing docs that follow.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
    @bearomorphism
    bearomorphism and Copilot committed May 30, 2026
    Configuration menu
    Copy the full SHA
    197ca17 View commit details
    Browse the repository at this point in the history

  2. docs(contributing): add agent-facing playbooks and validation guide 

    Adds docs/contributing/agents/ with a router index, a validation guide (targeted-test map + CI failure recipes), and five task playbooks for recurring contributions: add a version provider, add a changelog format, add or modify a CLI flag, deprecate a public API, and update snapshots/screenshots.

Aggressively deduplicates against existing human docs (contributing.md, contributing_tldr.md, pull_request.md, command pages) by linking rather than restating. Adds one-line `For AI agents'' callouts in contributing.md and pull_request.md so human contributors discover the parallel track.

Hooks the new pages into mkdocs nav under a new `For AI Agents'' section and into the mkdocs-llmstxt plugin so they appear in llms-full.txt.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
    @bearomorphism
    bearomorphism and Copilot committed May 30, 2026
    Configuration menu
    Copy the full SHA
    cf16a87 View commit details
    Browse the repository at this point in the history

  3. docs(agents): slim AGENTS.md to a routing layer 

    AGENTS.md is auto-loaded into every agent session, so its budget is tight. Trim it to the cross-cutting rules that an agent needs every time and link out to the new docs/contributing/architecture.md, docs/contributing/agents/index.md, and the validation guide and playbooks for everything else.

Drops content that now duplicates the human contributor docs (bootstrap commands, poe cheat sheet, thin coding-guidelines section, CI-failure patterns) and replaces it with a Do-Not-Touch list of generated/managed files and a short list of mandatory PR reminders (AI disclosure, `poe all` before push, Steps to Test, Conventional Commits).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
    @bearomorphism
    bearomorphism and Copilot committed May 30, 2026
    Configuration menu
    Copy the full SHA
    157cb18 View commit details
    Browse the repository at this point in the history

  4. style(docs): unwrap hard-wrapped paragraphs in new agent docs 

    The repository convention is unwrapped paragraphs (one line per logical paragraph) - see existing contributing.md and pull_request.md where lines run to ~150-250 chars. The newly added AGENTS.md, architecture.md, and docs/contributing/agents/ files were authored with a ~70-char hard wrap, breaking the convention. Unwrap them to match.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
    @bearomorphism
    bearomorphism and Copilot committed May 30, 2026
    Configuration menu
    Copy the full SHA
    741ee63 View commit details
    Browse the repository at this point in the history

  5. docs(agents): trim Do-Not-Touch to commitizen-specific traps 

    Drop `uv.lock` and the cache/build-artifact list (.mypy_cache, .ruff_cache, .venv, site, coverage.xml, ...) — those are generic lockfile/gitignore conventions that any modern agent already knows. Keep only the commitizen-specific files that get regenerated by cz bump, cz changelog, poe doc:screenshots, and poe test:regen, which an agent could not infer from convention alone.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
    @bearomorphism
    bearomorphism and Copilot committed May 30, 2026
    Configuration menu
    Copy the full SHA
    801fc2a View commit details
    Browse the repository at this point in the history

  6. docs(agents): drop redundant Agent-specific deltas section 

    The four items in this section all duplicated content from AGENTS.md's Mandatory PR reminders (PR template, poe all vs poe ci, do-not-touch) or pointed at validation.md (targeted tests). The `When to read what` table above already routes readers to the same destinations in a more compact form, so the section was pure noise.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
    @bearomorphism
    bearomorphism and Copilot committed May 30, 2026
    Configuration menu
    Copy the full SHA
    f1d1fcd View commit details
    Browse the repository at this point in the history

  7. docs(agents): cut more redundant content 

    Second redundancy audit. Drop content that duplicated other docs:

* agents/index.md: remove `Source-of-truth map` table; it duplicated
  the `When to read what` table below it. The dedup rule is still
  enforced by the `Updating these pages` section.
* agents/index.md: collapse the `fall back to the general flow`
  numbered list to a single sentence; the steps were generic
  engineering advice already covered by `AGENTS.md` and the
  pull-request template.
* validation.md: drop the `mypy --python-version 3.10` snippet; the
  identical command already lives in `contributing_tldr.md`.
* validation.md: drop the `Pre-commit hooks` section; `contributing.md`
  already covers `poe setup-pre-commit` and how hooks run.
* AGENTS.md: trim `When unsure` to the backward-compatibility rule;
  the other two bullets were generic agent etiquette.
* AGENTS.md: drop the `Follow Conventional Commits` reminder;
  every commitizen contributor knows this and prek enforces it.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
    @bearomorphism
    bearomorphism and Copilot committed May 30, 2026
    Configuration menu
    Copy the full SHA
    ac589a8 View commit details
    Browse the repository at this point in the history

  8. docs(agents): fix incorrect playbook examples 

    Validation against the actual source code surfaced three inaccuracies:

* add-version-provider.md: `composer_provider.py` was labelled
  `JSON file with non-standard layout`, but it is actually the
  simplest `JsonProvider` (just `filename` and `indent`). Replace
  with `npm_provider.py` for the non-standard layout / multi-file
  case, and re-introduce composer as the simplest-case example.
* add-changelog-format.md: pointed agents at
  `restructuredtext.py` as an example of overriding only
  `parse_version_from_title` + `parse_title_level`. RST actually
  overrides `get_metadata_from_file` because its titles span
  multiple lines. Re-route the line-anchored example to
  `markdown.py` / `asciidoc.py` / `textile.py` and keep RST as
  the multi-line example. Add the multi-line escape hatch to Step 2
  and clarify that the template extension comes from the class
  attribute, not the format name.
* architecture.md: claimed entry points are loaded `lazily`. Only
  providers are looked up at call time; `KNOWN_CHANGELOG_FORMATS`
  is populated at module import time. Drop the misleading qualifier.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
    @bearomorphism
    bearomorphism and Copilot committed May 30, 2026
    Configuration menu
    Copy the full SHA
    6dda294 View commit details
    Browse the repository at this point in the history
Loading