docs(contributing): add agent-facing playbooks and architecture overview#2007
Open
bearomorphism wants to merge 8 commits into
Open
docs(contributing): add agent-facing playbooks and architecture overview#2007bearomorphism wants to merge 8 commits into
bearomorphism wants to merge 8 commits into
Conversation
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>
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>
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>
Contributor
🔍 Commitizen bump previewNo commits in this PR are eligible for a version bump. |
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>
Contributor
🔍 Commitizen bump previewNo commits in this PR are eligible for a version bump. |
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>
Contributor
🔍 Commitizen bump previewNo commits in this PR are eligible for a version bump. |
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>
Contributor
🔍 Commitizen bump previewNo commits in this PR are eligible for a version bump. |
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>
Contributor
🔍 Commitizen bump previewNo commits in this PR are eligible for a version bump. |
Contributor
There was a problem hiding this comment.
Pull request overview
Docs-only change that introduces an agent-facing contributor track and a general-purpose architecture overview, while slimming AGENTS.md into a routing layer that defers detail to the per-topic pages.
Changes:
- Adds
docs/contributing/architecture.mdplusdocs/contributing/agents/(index, validation guide, 5 playbooks) and wires them intomkdocs.ymlnav and thellmstxtplugin sections. - Adds Material
!!! tipcallouts linking to the new agent index fromcontributing.mdandpull_request.md. - Replaces duplicated bootstrap/CI/coding-guideline content in
AGENTS.mdwith a routing table, a "Do not touch" list, and mandatory PR reminders.
Reviewed changes
Copilot reviewed 12 out of 12 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
mkdocs.yml |
Adds Architecture page under Contributing, new "For AI Agents" nav section, and corresponding llmstxt entries. |
docs/contributing/contributing.md |
Adds tip admonition linking to the new agent docs. |
docs/contributing/pull_request.md |
Adds tip admonition linking to the new agent playbooks. |
docs/contributing/architecture.md |
New page mapping subsystems, extension points, config layering, command flow, and test mirror. |
docs/contributing/agents/index.md |
Router page with source-of-truth map, "when to read what" table, and playbook index. |
docs/contributing/agents/validation.md |
Targeted-test selector map, poe all vs poe ci guidance, and CI-failure recipes. |
docs/contributing/agents/playbooks/add-version-provider.md |
Playbook for adding a built-in version provider. |
docs/contributing/agents/playbooks/add-changelog-format.md |
Playbook for adding a built-in changelog format. |
docs/contributing/agents/playbooks/add-cli-flag.md |
Playbook for adding/modifying a CLI flag and corresponding config. |
docs/contributing/agents/playbooks/deprecate-public-api.md |
Playbook for adding a deprecation window before removal. |
docs/contributing/agents/playbooks/update-snapshots.md |
Playbook for regenerating pytest-regressions snapshots and CLI help screenshots. |
AGENTS.md |
Slims to project pitch, "Read before changing" table, "Do not touch" list, and PR reminders; links out to the new docs. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
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>
Contributor
🔍 Commitizen bump previewNo commits in this PR are eligible for a version bump. |
bearomorphism
added a commit
that referenced
this pull request
May 30, 2026
The PR bump preview workflow passed �ody-includes to peter-evans/create-or-update-comment@v5, but that action has no such input -- it only creates a new comment, or updates one passed via comment-id. Every run therefore appended another duplicate comment (e.g. 6 stacked on #2007). Insert a peter-evans/find-comment@v3 step ahead of the post step to look up an existing preview comment by sentinel marker and bot author, then pass its id (empty for the first run) to create-or-update-comment. This matches the documented pattern in the action's README and keeps the bump preview as a single sticky comment per PR. Apply the same fix to the docs/tutorials/github_actions.md example so other projects copying the workflow don't inherit the bug, and also bump the example from create-or-update-comment@v4 to @v5 to match the workflow. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
8 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Adds an agent-shaped contributor track that links back to the existing human docs instead of restating them, and slims
AGENTS.mdto a routing layer.Why.
AGENTS.mdcurrently mixes routing, bootstrap commands, CI failure patterns, and coding guidelines that duplicatecontributing.md/contributing_tldr.md/pull_request.mdand drift out of sync. Nothing in the repo is reusable for recurring agent task types (add a provider, deprecate an API, regenerate snapshots, ...), so every session re-derives the workflow.What.
docs/contributing/architecture.md— one-page subsystem map (cli, commands, config, providers, changelog_formats, version_schemes, plugins) with extension points and config layering. General-audience.docs/contributing/agents/— routerindex.mdwith a source-of-truth map,validation.md(targeted-test selectors +poe allvspoe ci+ CI failure recipes), and 5 playbooks: add a version provider, add a changelog format, add/modify a CLI flag, deprecate a public API, update snapshots/screenshots.AGENTS.mdslimmed: keeps project pitch, key entrypoints, the "Read before changing" table; adds a "Do not touch" list of auto-managed files and the mandatory PR reminders; drops everything that now duplicates a human doc.contributing.mdandpull_request.md.mkdocs-llmstxtso the pages appear inllms-full.txt.Dedup rule. Every fact lives in exactly one place. The source-of-truth map in
agents/index.mdenforces it — agent docs link to human docs, never restate them.Checklist
Was generative AI tooling used to co-author this PR?
Generated-by: GitHub Copilot CLI following the guidelines
Code Changes
Docs-only PR. No Python, dependencies, or CI workflows changed.
uv run poe alllocally to ensure this change passes linter check and testsDocumentation Changes
uv run poe doclocally to ensure the documentation pages renders correctly (usedpoe doc:buildfor finite output)Expected Behavior
A new "For AI Agents" section appears under Contributing in the rendered docs,
llms-full.txtincludes the new pages, andAGENTS.mdis shorter and routes to them.Steps to Test This Pull Request
git checkout docs/agent-playbooks && uv sync --frozen --all-groupsuv run poe doc:build— confirm no broken-link warnings.site/contributing/agents/index.htmland walk the cross-links.site/llms-full.txtand confirm the new entries appear under Contributing.Additional Context
Split into 3 commits (architecture, agent docs + nav + callouts, AGENTS.md slim) for review clarity; squash-merge friendly.