Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 11 additions & 5 deletions quest/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,8 @@ Nightly, and any fix that cannot wait for its milestone, breaking or not.
m1 holds this cycle's additive work: improvements and fixes that need no
semver-breaking release, so each ships with the next cut or as a `release`
patch when backported. m2 is the next breaking release: every change that
would need one if it landed right after the cut, plus the
cut gate the [release cut](/quest/m3/release/cut.md) re-creates there. The cut waits on m2 alone. m3 and m4
would need one if it landed right after the cut. The
[release cut](/quest/m3/release/cut.md) waits on m2 alone. m3 and m4
are later work split by priority: m3 holds what a named consumer waits on,
release execution, and bug fixes in shipped code; m4 holds tests, tooling,
benchmarks, optimizations, and features nobody waits on yet. m5 holds work
Expand All @@ -30,7 +30,8 @@ Until the cut, [m4](/quest/m4/README.md) and [m5](/quest/m5/README.md)
require the [release cut](/quest/m3/release/cut.md) (decided 2026-11-13,
maintainer), so spare capacity goes to m0 to m3 and then to m9's lab work
instead of to later features. m3 stays open, since it holds the cut and its
reviews. The cut's PR deletes the cut quest, which lifts the gate.
reviews. The cut's PR lifts m4's gate and moves m5's to the next cycle's
wire cut, below.

No quest requires one in a later milestone (decided 2026-11-13, maintainer):
a blocker ranks by its own milestone, so the earlier quest would stall behind
Expand Down Expand Up @@ -69,7 +70,7 @@ milestones (decided 2026-10-19, rule replaced 2026-11-05 and 2026-11-09). The
[release cut](/quest/m3/release/cut.md) does both:

- The next cut moves remaining release-execution quests to a release epic in
m0, where each cut re-creates its successor, and sorts m3's
m0, where the on-demand additive and API cuts recur, and sorts m3's
other quests by kind: additive into m1, API breaks into m2, wire changes
stay in m3. m4 keeps its quests as later work of higher priority, m5 starts
empty as later work of lower priority, and today's m5 moves to m6, the
Expand All @@ -83,7 +84,12 @@ Ordering holds the phases: m1 work ranks first, and while `phase` in
`version.json` is `additive`, Nightly and the cut refuse a public API break on
`main`. Wire work is held by planning alone: it waits in m3 until the
maintainer opens the wire phase. The cut gate is re-created in m3, which the
cycle's last cut waits on. The hygiene audits recur behind the cut in the
cycle's last cut waits on. That wire cut lives in m4, the higher-priority
later-work milestone: it requires m2 and m3, so it can't sit in an earlier
milestone or in the m3 it waits on (decided 2026-11-14, under /quest-afk,
for the maintainer's review). m5 and m6 require it, so each cycle
spare capacity goes to m0 to m4 and then to m9, and m5's quests start once
the shift brings them into m4. The hygiene audits recur behind the cut in the
higher-priority later-work milestone (m3 until the next cut, m4 after it), so
the shift brings each into m1.

Expand Down
33 changes: 0 additions & 33 deletions quest/m0/cut-placement.md

This file was deleted.

5 changes: 2 additions & 3 deletions quest/m2/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,9 +3,8 @@
## Goal

Every change that would need a semver-breaking release if it landed right
after the next cut of `main` into `release`, plus the cut
gate, which the [release cut](/quest/m3/release/cut.md) re-creates here each
cycle. The cut waits on this milestone alone;
after the next cut of `main` into `release`. The
[release cut](/quest/m3/release/cut.md) waits on this milestone alone;
complete it before cutting main into release.

## Plan
Expand Down
92 changes: 62 additions & 30 deletions quest/m3/release/cut.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,22 +57,48 @@ both fixes reach release.
Recurs once per cut (decided 2026-10-19 as once per major release; per cut,
in three kinds, 2026-11-09). The kinds, what each publishes, and which checks
each runs are in [Releases](/RELEASE.md#releases). This run is the
`0.22.0` cut: it still waits on all of m2. Once it merges into `release` and
`0.22.0` cut: it still waits on all of m2, and it ends this cycle like a wire
cut. Once it merges into `release` and
release-plz has published every package it bumps (the API diff's baselines), a
PR on `main` sets `phase` in `version.json` to `additive` (the cut PR keeps
the old phase, so its API diff only reports its breaks) and performs the re-split the root
[questline](/quest/README.md) describes. This epic's remaining publication and
adoption quests move to a release epic in m0, m3's other quests sort by kind
into m1 (additive), m2 (API breaks) and m3 (wire changes), m4 stays, m5 moves
to m6 and m5 starts empty, each milestone README's Goal is rewritten for its
new role, and each audit's recurrence names m4 instead of m3.

Every cut's PR removes this path from every `Required`, which releases the
audits waiting on it, rewrites every link to a moved path, and re-creates this
quest as `/quest/m0/release/cut.md`, in m0's release epic (created if the
cut moved nothing there), keeping its Goal and this paragraph, with no `Required` and a `## Waiting` item for the
maintainer's instruction naming the next cut and its kind. Each later run
follows that kind:
to m6 with its `Required` and a new empty m5 requires the wire cut too, each
milestone README's Goal and current Plan rule are rewritten for its new
role (dated decision entries stay as history), and each audit's
recurrence names m4 and the wire cut instead of m3 and this path.

Every cut's PR removes its own path from every `Required`, which releases the
quests waiting on it, and rewrites every link to a moved path. Each cut
recurs as one of two quests, which keep their Goal, these recurrence
paragraphs, and the cut gate template with its decision:

- **The on-demand cut**, `/quest/m0/release/cut.md` in m0's release epic
(created if the cut moved nothing there): the next additive or API cut. It
has no `Required` and a `## Waiting` item for the maintainer's instruction
naming the cut and its kind. Any quest that waits only for the next
publication requires it. Every cut's PR, the wire cut's included, removes
this path from every `Required` and re-creates it.
- **The wire cut**, `/quest/m4/wire-cut.md`: the cut that ends the cycle. It
requires `/quest/m2/README.md` and `/quest/m3/README.md`, so it becomes
ready once the cycle's API breaks, wire changes, and the cut gate in m3
have merged, and it has no `## Waiting`, since the maintainer opens the
wire phase before that. [m5](/quest/m5/README.md) and m6 require it: the
gate that holds later work while m9's lab stays open. The hygiene audits
and the vendor sync's children recur behind it in m4. Its PR re-creates it
at the same path and keeps the m5 and m6 links, so the gate holds the next
cycle too; m5's quests reach m4 in the shift, which is when they can start.

The wire cut lives in m4 because no quest requires one in a later milestone,
so it sits in or after m3, the last milestone it waits on; m3 can't hold it,
since a quest can't require the milestone that holds it. A milestone can't
require the cut it holds either, so m4 stays open and the gate covers the
milestones after it. The on-demand cut waits on no milestone, so it stays in
m0, where its publication follow-ups live and anything can require it.

Each run follows its kind:

- **Additive**: the readiness checks, with the API diff refusing any break.
Changed JS packages and binding wrappers take patch bumps on `main` first;
Expand All @@ -81,21 +107,24 @@ follows that kind:
review](/quest/m3/release/api-review.md), the [feature
review](/quest/m3/release/feature-review.md), the [Cargo feature
review](/quest/m3/release/feature-flags.md), and the [migration
audit](/quest/m3/release/migrate-audit.md) beside it in m0's release
audit](/quest/m3/release/migrate-audit.md) in m0's release
epic, each keeping
its Goal and recurrence paragraph, scoped to what changed since the last
breaking cut and requiring nothing, and add them to this quest's
breaking cut and requiring nothing, and add them to the cut's
`Required`. Then advance the shared minor with `just version`.
- **Wire**, which ends the cycle: also require `/quest/m2/README.md` and
`/quest/m3/README.md`, which the cut can wait on because it lives in m0,
not m3; finalize the cycle's wire version, then, once it merges
into `release` and its packages are published, set `phase` back to `additive` on `main`, and shift the milestones: remaining publication and adoption
quests to m0, m4's quests by kind into m1, m2 and m3, m5's to m4, and m6
stays the deferred bucket.

The `0.22.0` cut and each wire cut also re-create the cut gate in m3 from the
- **Wire**, which ends the cycle: finalize the cycle's wire version, then,
once it merges into `release` and its packages are published, set `phase`
back to `additive` on `main`, and shift the milestones: remaining
publication and adoption quests to m0, m4's quests other than the wire cut
by kind into m1, m2 and m3, m5's to m4, and m6 stays the deferred bucket.
Rewrite the Goal and the current Plan rule of each milestone it moves (m4,
m5, m6) to match, so no README keeps a rule from an older split.

The `0.22.0` cut re-creates both quests, points m5's `Required` at the wire
cut in place of this path, and drops m4's, so m4 opens. It and each wire cut
also re-create the cut gate in m3 from the
template below; a recurring cut-gate child that the last run re-created in
the later-work milestone, such as the [vendor
m4, such as the [vendor
sync](/quest/m3/vendor-sync/README.md), moves under it.
Only `/quest-delete` ends the recurrence.

Expand All @@ -114,16 +143,20 @@ merged moq-e2ee and moq-sign into moq-crypto (decided 2026-11-02, no yank):
[retired names](/quest/m3/release/retired-names.md) publishes the pointer
above 0.0.25, with the other names this cut stops publishing.

Open as of 2026-11-13 (maintainer, /quest-plan): where the next cycle's cuts
live. The steps above place them in m0's release epic and have the wire cut
require m2 and m3, but no quest may require one in a later milestone, and
[m4](/quest/m4/README.md) and [m5](/quest/m5/README.md) now require this cut
until it lands, a gate each cycle should re-create. [Cut
placement](/quest/m0/cut-placement.md) settles both before this cut
re-creates its successor.
Decided 2026-11-14 ([cut placement](https://github.com/moq-dev/moq/pull/8736),
taken by the agent under /quest-afk, for the maintainer's review): ✅ the
wire cut lives in m4 and gates m5 and m6 every cycle, while additive and API
cuts recur in m0. Rejected: one cut quest in m0 that requires m2 and m3 for
a wire cut (breaks the 2026-11-13 rule); the wire cut in m3 requiring each m3
entry by hand (a list nobody keeps current, like the hand-kept m2 list
rejected 2026-11-09); one cut quest in m4 for every kind (additive and API
cuts would rank last, nothing in m0 to m3 could require one, and every
additive cut would have to pick which links to keep); lifting the gate between
cycles (nothing marks a moment to lift it, and m5's work reaches m4 at each
shift anyway).

Cut gate template (moved here 2026-11-09 from the gate's own Plan; see the
decision below). The gate is an epic in m3 for the checks the cut needs that
decision below). The gate is an epic in m3, `/quest/m3/cut-gate/`, for the checks the cut needs that
break nothing: `main` is no slower than `release`, vendored code has the
upstream fixes it needs, and the hand-written `moq-c` is at parity with
moq-ffi. It has no work of its own and completes when every child merges. It
Expand Down Expand Up @@ -173,7 +206,6 @@ with the suites above.

## Required

- [Cut placement](/quest/m0/cut-placement.md) - where this cut re-creates its successor, and the gate it re-creates
- [Breaking release readiness](/quest/m2/README.md) - code, protocol and package proofs
- [Migration audit](/quest/m3/release/migrate-audit.md) - every break on the cut PR has its MIGRATE.md entry
- [API shape review](/quest/m3/release/api-review.md) - every new or changed public API was reviewed for a better shape, and approved changes landed
Expand Down
13 changes: 7 additions & 6 deletions quest/m3/vendor-sync/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,13 +39,14 @@ This README's own work, once every child has merged:
vendored commit. Code whose upstream is gone or frozen (moq-tokio's
`quic::web`, from moq-dev/noq) is listed in the README it lives in and
gets no child.
2. Re-create the questline at `/quest/m3/vendor-sync/`. Every child keeps its Goal and carries
2. Re-create the questline at `/quest/m4/vendor-sync/`. Every child keeps its Goal and carries
forward its last checked commit and what this run learned (what to check
first, what was ruled out). Each child requires
[the release cut](/quest/m3/release/cut.md), which removes itself from
every `Required` and moves the questline under the re-created
cut gate (`quest/m2/cut-gate/`) in m2, so the next run becomes
ready there, once per release cycle (rule replaced 2026-11-05).
first, what was ruled out). Each child requires the cycle's wire cut
(`/quest/m4/wire-cut.md`, which [the release cut](/quest/m3/release/cut.md)
re-creates), which removes itself from every `Required` and moves the
questline under the re-created cut gate (`/quest/m3/cut-gate/`) in m3, so
the next run becomes ready there, once per release cycle (rule replaced
2026-11-05 and 2026-11-14).
3. Drop a child whose code was deleted or whose upstream stopped mattering,
saying why in the PR.

Expand Down
10 changes: 9 additions & 1 deletion quest/m4/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,15 @@ Decided 2026-11-13 (maintainer, /quest-plan): this milestone requires the
to m0 to m3 and then to [m9](/quest/m9/README.md)'s lab work (rejected:
requiring m0, m1, and m2, which lifts only when they empty, and m0 rarely
does; also gating m3, which holds the cut). The cut's PR deletes the cut
quest, which lifts this gate.
quest, which lifts this gate for good: from then on m4 holds each cycle's
wire cut, which it can't require.

Current rule: m4 holds the wire cut and the work behind it, and moves only
at a wire cut, whose shift sorts its other quests by kind into m1 (additive),
m2 (API breaks) and m3 (wire changes) and brings m5's quests in. It does not
empty after every cut. A quest here that gains a consumer moves to m3; one
that loses its last reason moves to the deferred milestone (m5 now, m6
after the `0.22.0` cut) or is deleted. The entries below are history.

Decided 2026-11-05 (maintainer, milestone re-cut): the lower half of the old
m2 ("later work"), as [m3](/quest/m3/README.md) describes. After each cut
Expand Down
9 changes: 8 additions & 1 deletion quest/m5/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,14 @@ Decided 2026-11-13 (maintainer, /quest-plan): this milestone requires the
to m0 to m3 and then to [m9](/quest/m9/README.md)'s lab work (rejected:
requiring m0, m1, and m2, which lifts only when they empty, and m0 rarely
does; also gating m3, which holds the cut). The cut's PR deletes the cut
quest, which lifts this gate.
quest and points this gate at the next cycle's wire cut, which keeps it
every cycle; m5's quests start once the shift brings them into m4.

Current rule: until the `0.22.0` cut, m5 is the deferred bucket, as below.
That cut moves it, with its `Required`, to m6, and the new m5 starts empty as
later work of lower priority, requiring the wire cut like m6; each wire
cut's shift moves m5's quests to m4, and m6 stays the deferred bucket. The
entries below are history.

A quest gated on the outside world has a condition quest beside it, as the
root [questline](/quest/README.md) describes. A speculative feature or study
Expand Down