Skip to content

docs: sweep branch references after v2 lands on main #1813

Description

@cliffhall

Once the branch runbook completes — v1 moves to v1/main and v2 becomes the default main — every doc that names a base branch goes stale. CONTRIBUTORS.md and .github/pull_request_template.md were already written against the post-runbook names in #1604, so this issue covers the rest.

Scope

Sweep the maintainer-facing docs for v2/main / "main is v1" phrasing and update to the new layout:

  • AGENTS.md
    • ## Repository & Project BoardBase Branches line (currently "v2/main (active), main (v1)").
    • ## Project Status and Direction → the whole section is written from the pre-cutover point of view ("The main branch currently contains the legacy version…", "Eventually, we will replace main with v2/main"). Rewrite for the post-cutover state.
    • The v1 policy wording: AGENTS.md says v1 "accepting bug fixes and minor improvement PRs" and the v1 board is "no new activity except security and bug fixes", but CONTRIBUTORS.md now states security fixes only. Pick one and make them agree.
    • ## Issue-driven Work Style → PR base-branch instructions and the Closes #N note, which is built entirely on "v2 PRs target v2/main, a non-default branch, so closing keywords do not auto-close." After the cutover v2 PRs target the default branch, so auto-close does fire — the manual "close the issue and move the card to Done on merge" step can go away.
  • README.md
    • The "Repo status" callout ("This is the v2 line … branch v2/main. The main branch is the legacy v1 implementation").
    • The Contributing section's "open PRs against v2/main" line.
  • Anything else that greps for v2/main — CI workflows, issue templates, specification docs where the branch name is load-bearing rather than historical.

Notes

  • Historical references (changelogs, spec docs describing what happened) can stay as-is — this is about instructions that would send someone to the wrong branch.
  • Do not start this before the runbook lands; the docs are correct until then.
  • Also decide at that point whether v1.5/main still needs its AGENTS.md "frozen, kept as a reference point, do not delete" note, or whether the branch gets deleted (raised in review on docs: add CONTRIBUTORS.md issues-only policy (closes #1517) #1604).

Metadata

Metadata

Assignees

Labels

v2Issues and PRs for v2

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions