Skip to content

Docs: post-#834 pass #932

Closed
Closed

Description

@thekevinbot

Documentation cleanup owed after the #834 CI path-trigger epic. Each item is independent; one PR can carry them all.

1. Retire the old workflow names from AGENTS.md

The epic collapsed the per-concern workflows into per-domain ones. AGENTS.md still names the retired files and jobs throughout (conventions.yml, python-test.yml, ts-test.yml, rust-test.yml, the "seven non-internals-checks Conventions lanes", docs.yml). Replace with the surviving set: dirsql-python-ci.yml, dirsql-typescript-ci.yml, dirsql-rust-ci.yml, plugin-dirsql-embedding-ci.yml, internals-checks-ci.yml, internals-distcheck-ci.yml, docs-ci.yml, docs-release.yml, release-ci.yml, changelog-check.yml, putitoutthere-config-check.yml, release.yml.

Also affects agents/reference/testing-conventions-ci.md and agents/reference/testing-gates.md, which describe the gates as living inside conventions.yml.

2. Rewrite the stale Mergify section

AGENTS.md's "PR Monitoring" section is written around anchor conditions — "success_conditions therefore names one anchor per unconditionally-triggered workflow (Conventions, Release Precheck, Release Config Check, Changelog Check)", "renaming a caller job id … requires the matching .mergify.yml edit in the same PR", "never anchor a path-filtered workflow", and the diagnostic guidance for "an unmet anchor".

#881 deleted every anchor. .mergify.yml on main is now:

success_conditions:
  - "#check-failure = 0"

All of that guidance is now wrong, including the failure modes it teaches contributors to look for. Rewrite against the current file.

3. Document the zero-check-merge policy

The corollary of #881 that nothing currently states: a PR that triggers zero checks is vacuously green and will merge. This is deliberate — it is the accepted cost of removing the anchors, whose coupling to trigger filters deadlocked the gate in #832 — but it is load-bearing and undocumented. Write it down explicitly, along with the consequence that a path-filtered workflow still in flight does not hold the gate.

The one class where this is a genuine gap rather than an accepted cost is CI-config-only PRs; that is tracked separately in #862 and should be cross-referenced here rather than re-argued.

4. Amend the #834 rules text for READMEs

The maintainer decision recorded during the stack's final review: package README edits keep requiring a changelog fragment. The gate behavior is correct as written (_is_exempt in internals/checks/src/checks/changelog_gate/decide.py treats READMEs as code) and needs no code change — only the rules text does. Amend #834's wording to:

READMEs → release-ci + changelog-check

READMEs ship in all three published artifacts (PyPI long-description, npm tarball, crate), which is why release-ci.yml deliberately does not exclude them while it does exclude fragment dirs.

5. Fix #885, and the MIGRATIONS.md asymmetry it sits next to

#885 ("Docs site publishes a permanently stale Migrations page") names the publisher as docs-deploy.yml. That file does not exist — the publisher is docs-release.yml. Correct the issue, then note the related asymmetry while fixing it:

Workflow Event MIGRATIONS.md in paths:?
docs-ci.yml pull_request no
docs-release.yml push to main yes

So a MIGRATIONS.md edit shows zero checks on its PR and then runs the publisher on main — the exact pre-#882 shape that docs-ci.yml was created to close, surviving for one file. #885's chosen fix (delete docs/migrations.md, drop MIGRATIONS.md from the publisher's paths) resolves the asymmetry by removing the trigger rather than adding it, which is the right direction given the file is frozen. Worth stating explicitly in that issue so the two entries are not re-added independently later.

Separately: docs-ci.yml has no self-path (.github/workflows/docs-ci.yml is absent from its own paths:), which #862's spec row 16 would flag.

Activity

  1. thekevinbot commented on Aug 20, 2026

    @thekevinbot
    CollaboratorAuthor

    Still owed, and its scope moved under it again: items 2 and 3 were written against anchor-less Mergify, but #950 has since removed Mergify entirely and restored pr-monitor as the gate (plus #954 dropped CODEOWNERS, #955 added gate concurrency). The rewrite should target the pr-monitor world, not .mergify.yml. Items 1 and 4 unchanged. Note AGENTS.md currently has ~13 stale Mergify/conventions.yml references.

  2. thekevinbot commented on Aug 20, 2026

    @thekevinbot
    CollaboratorAuthor

    Item 1 misses one file: agents/reference/e2e-attestation.md:6 also places the gate inside the retired workflow — "The freshness check runs inside the reusable workflow (conventions.yml, the python-sdk / typescript-sdk e2e-verify gate)".

    So the item-1 file set is AGENTS.md plus all three of agents/reference/{testing-conventions-ci,testing-gates,e2e-attestation}.md.


    Generated by Claude Code

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions