Skip to content

Commit b5f041d

Browse files
committed
docs: align agent branch policy with Go port endgame
Replace dual-track landing guesses with owner intake rules: dev2-go as home base, dev allowed only with dev2-go coverage before merge, planned FF collapse.
1 parent af0a18c commit b5f041d

2 files changed

Lines changed: 53 additions & 45 deletions

File tree

‎AGENTS.md‎

Lines changed: 36 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -40,45 +40,48 @@ Read the nearest nested `AGENTS.md` before changing files in a scoped directory.
4040

4141
## Branch targets
4242

43-
- **`dev`**
44-
- Purpose: Default integration branch.
45-
- Pull-request rule: All normal changes target `dev`.
43+
Interim Go-port endgame (owner direction). `MAINTAINERS.md` is authoritative.
4644

4745
- **`dev2-go`**
48-
- Purpose: Parallel Go native-port integration line.
49-
- Pull-request rule: Use only when the primary purpose is Go native-port work and the change touches `go/`, `bin/native-runtime.mjs`, `src/lib/runtime-entry.ts`, or Go release-asset tooling.
46+
- Purpose: Current home base for dogfooding, triage, and most product work.
47+
Strict superset of `dev` (has TS **and** `go/`).
48+
- Pull-request rule: Features, behavior changes, and anything that must keep
49+
TS + Go in sync target `dev2-go` (one PR). Prefer this for open product PRs.
50+
51+
- **`dev`**
52+
- Purpose: Current release-path integration line (still TS toward `main` /
53+
`latest` until Go graduates through `preview`).
54+
- Pull-request rule: `dev` PRs are allowed, but **do not merge** until the
55+
same change is also on `dev2-go` (rebase/retarget there and/or add the Go
56+
side). Urgent “latest is on fire” hotfixes may land on `dev` first with
57+
`needs-go-port`, then follow up on `dev2-go`. Tiny non-behavior work
58+
(docs / CI / governance) may stay on `dev`.
5059

5160
- **`main`**
52-
- Purpose: Release branch.
53-
- Pull-request rule: Maintainer-controlled promotion from `dev` only. Do not target feature pull requests here.
61+
- Purpose: Release branch (`latest`).
62+
- Pull-request rule: Maintainer-controlled promotion from `dev` only. Do not
63+
target feature pull requests here. After `dev` is fast-forwarded to
64+
include Go, do not promote `dev` → `main` until preview has baked (freeze
65+
lands with that fast-forward).
5466

5567
- **`preview`**
56-
- Purpose: Prerelease train.
57-
- Pull-request rule: Maintainer-directed prerelease work only.
68+
- Purpose: Prerelease train (`preview` dist-tag) for baking Go before `latest`.
69+
- Pull-request rule: Maintainer-directed prerelease work only. Prefer
70+
merge/ff only — do not force-push.
5871

5972
A pull request targeting neither `dev` nor `dev2-go` is invalid unless it is a
60-
maintainer-controlled release or promotion. A pull request targeting `dev2-go`
61-
without the required Go/native scope must be retargeted to `dev`.
62-
63-
### Interim dual-track intent (`dev` and `dev2-go`)
64-
65-
The Go port is still stabilizing, so the project is moving toward **two release
66-
tracks** rather than one shared line:
67-
68-
- `dev` — TypeScript / Bun track (current release path to `main`)
69-
- `dev2-go` — Go track (may gain its own separate release path; still contains
70-
shared TypeScript surfaces today)
73+
maintainer-controlled release or promotion. Do **not** open duplicate PRs for
74+
the same change on both lines; maintainers sync by rebasing `dev2-go` onto
75+
`dev`. Contributors never stack the same commits twice.
7176

72-
Owner direction for handling issues and PRs: keep both tracks in mind, and
73-
prefer landing work on **both** `dev` and `dev2-go` when the change belongs on
74-
both, until a pipeline or separate Go release path is decided. Exact mechanics
75-
(which base first, cherry-pick vs paired PR, whether `dev2-go` ships alone) are
76-
still being decided — do not invent dual-base PRs, and do not treat the old
77-
“`dev2-go` = Go-only work” rule as the whole story anymore.
77+
### Endgame (planned)
7878

79-
Prefer promoting and deploying release-path work within about a week when
80-
maintainers direct it. `MAINTAINERS.md` is authoritative; update it when the
81-
owner finalizes the pipeline / separate-release decision.
79+
1. Fast-forward `dev` to `dev2-go`, then retire `dev2-go` as an intake target
80+
(keeps existing `dev`-keyed automation).
81+
2. Release staging: `dev` (Go) → `preview` → `main` (`latest`), keeping
82+
`latest` on TS until `preview` has baked.
83+
3. No separate long-lived TS npm channel; TS remains oracle / unsupported-target
84+
fallback.
8285

8386
## Working rules
8487

@@ -140,7 +143,10 @@ These rules apply to human and automated reviews.
140143
- Report only concrete correctness, security, compatibility, privacy, or maintainability failures.
141144
- Name the file and line, describe the reproducible failure mode, explain impact, and suggest a specific fix.
142145
- Do not report vague concerns, personal style preferences, or hypothetical failures without a credible execution path.
143-
- Verify the target branch against the branch-target rules above.
146+
- Verify the target branch against the branch-target rules above. Flag a `dev`
147+
PR that is merge-ready without the same change covered on `dev2-go` (except
148+
tiny non-behavior docs/CI/governance). Do not ask authors to retarget away
149+
from `dev2-go` merely because the diff is not Go-only.
144150
- Require focused regression coverage for behavior changes.
145151
- Require documentation updates for user-facing behavior changes.
146152
- Do not claim a check, platform, security review, or CI result passed unless it actually ran and passed.

‎MAINTAINERS.md‎

Lines changed: 17 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -16,21 +16,23 @@ through GitHub repository settings.
1616

1717
## Review and merge policy
1818

19-
- Pull requests still use **one** GitHub base per PR. `dev` remains the default
20-
TypeScript / Bun integration line and the current path to `main`. `dev2-go`
21-
is the Go track; it also carries shared TypeScript today. The target-branch
22-
check accepts both bases.
23-
- **Interim dual-track intent:** the Go port is still finding instability, so
24-
the owner wants two release tracks and is still deciding whether `dev2-go`
25-
can ship separately. Until that is finalized (and until any sync pipeline
26-
lands), when handling issues or PRs prefer getting the same change onto
27-
**both** `dev` and `dev2-go` when it belongs on both (cherry-pick, paired PR,
28-
or maintainer sync). Do not treat “merged to one track only” as finished if
29-
the other track still needs it. Do not hard-code a finished workflow beyond
30-
what the owner has confirmed.
31-
- Promotion to `main` and npm releases remain maintainer-controlled from `dev`
32-
until a separate Go release path exists. Prefer promoting and deploying
33-
within about a week when the owner or maintainers direct it.
19+
- Pull requests use **one** GitHub base. The target-branch check accepts `dev`
20+
and `dev2-go`.
21+
- **Interim intake (Go-port endgame):** `dev2-go` is the home base for
22+
dogfooding, triage, features, and behavior changes (it has TS and `go/`).
23+
`dev` PRs are allowed, but must not merge until the same change is also on
24+
`dev2-go` (rebase/retarget and/or add Go code there). Urgent latest hotfixes
25+
may merge to `dev` first with `needs-go-port`, then follow up on `dev2-go`.
26+
Tiny non-behavior docs/CI/governance may stay on `dev`. Do not ask
27+
contributors for duplicate PRs of the same change; maintainers rebase
28+
`dev2-go` onto `dev` to sync.
29+
- **Planned collapse:** fast-forward `dev` to `dev2-go`, then retire `dev2-go`
30+
as an intake target. Release staging after that is `dev` → `preview` →
31+
`main`, keeping `latest` on TS until `preview` has baked. The
32+
`dev` → `main` promotion freeze lands together with that fast-forward.
33+
- Promotion to `main` and npm releases remain maintainer-controlled from `dev`.
34+
Prefer promoting and deploying within about a week when the owner or
35+
maintainers direct it.
3436
- A pull request requires approval from at least one maintainer and successful required CI checks
3537
before merge.
3638
- Authors do not approve their own pull requests.

0 commit comments

Comments
 (0)