docs: per-package MIGRATE.md as the single source for breaking changes

AGENTS.md

@@ -58,6 +58,7 @@ The API is the most important thing to get right.
 A bad shape costs a breaking change in every language, and the surface is huge.
 
 - Report the public API and wire impact of every change, in the PR description and whenever asked.
+- A breaking change adds an entry under `## Unreleased` in each affected package's `MIGRATE.md` saying how to migrate.
 - Keep things private until a consumer needs them. Scrutinize every new exported item.
 - Never add `foo_with_x`, `foo_checked`, or a compatibility shim. Make the breaking change to `foo` instead.
 - Let the type system make misuse unrepresentable

CONTRIBUTING.md

@@ -15,7 +15,7 @@ Have at least these sections:
 
 - **Problem**: a summary of the problem and why this PR is needed.
 - **Approach**: a summary of the approach taken to solve the problem.
-- **Impact**: a bullet point for every public API/wire change made.
+- **Impact**: a bullet point for every public API/wire change made. A breaking one also gets a `MIGRATE.md` entry in each affected package.
 - **Alternatives**: any alternative approaches considered.
 - **Follow-ups**: any issues encountered or quests created.
 
@@ -83,6 +83,7 @@ For an advisory against Quinn, follow the advisory triage in [`rs/moq-quic/READM
 `main` is the trunk; `release` is what ships, and release-plz and every branch-triggered publish run only there.
 
 - A release is cut by hand: a PR merging `main` into `release`, with a merge commit.
+- A breaking cut first renames, on `main`, each changed `MIGRATE.md`'s `## Unreleased` to its version transition (`## 0.3 -> 0.4`), leaving an empty `## Unreleased` above it.
 - Suggest a `release` backport for any serious bug fix (crash, security, data loss, broken interop), whether found on `main` or reported against a release. Land it on `main` first, then port it onto `release` as a separate PR that keeps the published API, so it ships as a patch.
 - After any release publishes, patch or breaking, run `just test wire-compat --remeasure` on `main` and land the rewritten `test/interop/compat/planned-breaks.json` with refreshed reasons. Otherwise the nightly wire-compat check fails on the stale pins.
 - Nothing merges `release` into `main` automatically. Before cutting a minor or breaking release, the maintainer merges `release` into `main` once, so trunk carries the published versions, CHANGELOGs, and any `release`-only commits. It lands as a merge commit with `--admin`, never squashed, so the cut starts from an advanced merge base.

cpp/moq/MIGRATE.md

@@ -0,0 +1,62 @@
+# Migrating the C++ moq library
+
+How to update your code for each breaking change, newest first.
+
+## Unreleased
+
+### Subscriptions carry group ranges (#5732)
+
+`Subscription::group_start` and `group_end` are replaced by `ranges`, a list of `Range` whose ends are an `Anchor` (an absolute group and frame, or a count of groups before the latest), and an optional `order`.
+To start at group `n`, pass one range starting at the absolute anchor for group `n`, frame 0.
+
+### Receive estimates come from `Session::recv_bandwidth` (#5777)
+
+The connection stats no longer carry a receive estimate.
+Hold the consumer `Session::recv_bandwidth` returns to request PROBE, read it with `peek()` or wait with `changed()`, and `cancel()` it to stop.
+
+```cpp
+auto bandwidth = session->recv_bandwidth();
+auto rate = bandwidth ? bandwidth->peek() : std::nullopt;
+```
+
+### `AnnouncedBroadcast::available()` waits for the next publisher instance (#5700)
+
+The first call returns the broadcast serving the path, as before.
+Each later call waits for the next instance to take over the path, instead of returning whatever serves it now.
+
+### A timed track refuses a group that rewinds (#5803)
+
+Writing a frame fails with `TimestampMismatch` when a group's first frame starts before a lower-sequence group's, or after a higher one's.
+A publisher whose timeline restarts publishes a new broadcast instead.
+
+### Bandwidth reserves a track's demand (#5845)
+
+`Bandwidth::reserve` takes the track's `demand()` instead of the producer, and no longer fails: pass `ok(track->demand())`.
+
+### Generated types drop the `Moq` prefix (#5727)
+
+`moq::MoqFoo` is `moq::Foo`, the name the aliases already gave it.
+`moq::expected` is `tl::expected` at every C++ standard instead of `std::expected` under C++23, and `MOQ_ABI`, `MOQ_ABI_NAME`, and `MOQ_IMPLEMENTATION` are gone.
+
+### Media subscribe and fetch take a catalog rendition (#5834)
+
+`moq::MediaTrackConfig` and `moq::MediaGroupConfig` replace `name` and `container` with a `moq::Rendition` and follow its broadcast and track themselves.
+
+```cpp
+auto media = ok(moq::MediaTrackConsumer::subscribe(broadcast, {moq::Rendition::kVideo{id, video}}).get());
+```
+
+### Native codecs have audio and video types (#5694)
+
+`BroadcastProducer::encode_audio` / `encode_video` are `moq::AudioProducer::init` / `moq::VideoProducer::init`, which take a `moq::MediaCatalogProducer`.
+The audio track name moves into `AudioEncoderOutput::track`, and a zero `frame_duration_us` takes the codec's own frame.
+`BroadcastConsumer::decode_audio` / `decode_video` are `moq::AudioConsumer::subscribe` / `moq::VideoConsumer::subscribe`, taking the broadcast first.
+Producers expose subscriber state only through `demand()`, and a video `gop` is a `moq::VideoGop` keyframe variant.
+`moq::AudioEncoder` / `moq::VideoEncoder` encode without publishing.
+
+```cpp
+moq::AudioEncoderOutput output{moq::AudioCodec::opus()};
+output.track = "audio";
+auto catalog = ok(moq::MediaCatalogProducer::init(broadcast));
+auto audio = ok(moq::AudioProducer::init(catalog, input, output, nullptr));
+```

cpp/obs/MIGRATE.md

@@ -0,0 +1,10 @@
+# Migrating the obs-moq plugin
+
+How to update your OBS setup for each breaking change, newest first.
+
+## Unreleased
+
+### The video bitrate follows the bandwidth estimate (#5845)
+
+The configured video bitrate is now a ceiling: the encoder drops below it when the uplink narrows, with no opt-out.
+An encoder shared with a recording follows too, so give the recording its own encoder to keep it at the full rate.

dart/moq/MIGRATE.md

@@ -0,0 +1,134 @@
+# Migrating the Dart moq package
+
+How to update your code for each breaking change, newest first.
+
+## Unreleased
+
+### Subscriptions carry group ranges (#5732)
+
+`Subscription.groupStart` and `groupEnd` are replaced by `ranges`, a list of `Range` whose ends are an `Anchor` (an absolute group and frame, or a count of groups before the latest), and an optional `order`.
+To start at group `n`, pass one range starting at the absolute anchor for group `n`, frame 0.
+
+### Receive estimates come from `Session.recvBandwidth` (#5777)
+
+The connection stats no longer carry a receive estimate.
+Hold the consumer `Session.recvBandwidth` returns to request PROBE, read it with `peek()` or wait with `changed()`, and `cancel()` it to stop.
+Replace `stats().estimatedRecvRateBps` with `recvBandwidth()?.peek()`.
+
+### `AnnouncedBroadcast.available()` waits for the next publisher instance (#5700)
+
+The first call returns the broadcast serving the path, as before.
+Each later call waits for the next instance to take over the path, instead of returning whatever serves it now.
+
+### A timed track refuses a group that rewinds (#5803)
+
+Writing a frame fails with `TimestampMismatch` when a group's first frame starts before a lower-sequence group's, or after a higher one's.
+A publisher whose timeline restarts publishes a new broadcast instead.
+
+### Bandwidth reserves a track's demand (#5845)
+
+`Bandwidth.reserve` takes the track's `demand()` instead of the producer, and no longer throws.
+Pass `demand: track.demand()` instead of `track: track`.
+
+### Media subscribe and fetch take a catalog rendition (#5834)
+
+`media.TrackConfig` and `media.GroupConfig` replace `name` and `container` with a `rendition` (`media.VideoRendition` or `media.AudioRendition`) and follow its broadcast and track themselves.
+
+```dart
+final config = media.TrackConfig(rendition: media.VideoRendition(id: id, config: video));
+```
+
+### Background panics are reported (#5562)
+
+A panic in a background task throws `TaskMoqException` with the panic message as `reason`, and other objects keep running.
+
+### Announcements are events with a restart
+
+`Moq.announcements()` is `announced(...).updates()`, a `Stream<AnnounceEvent>`: `AnnounceEventStart`, `AnnounceEventUpdate`, `AnnounceEventEnd`, or `AnnounceEventRestart`, each carrying an `Announce`.
+`AnnounceUpdate` is gone.
+A restart means another publisher instance now serves the prefix: request the path again.
+
+```dart
+moq.announced().updates().listen((event) {
+  switch (event) {
+    case AnnounceEventStart(:final announce) ||
+        AnnounceEventRestart(:final announce):
+      subscribe(announce.prefix);
+    default:
+  }
+});
+```
+
+### "Epoch" means only the publisher epoch (#5146)
+
+`Moq.epoch` is `connects`.
+
+### The consume origin is `consume`
+
+`ConnectOptions.subscribe` is `consume`.
+A value the native side cannot use fails `Moq.connect` with `ConfigMoqException`, including a bad bind address.
+A server request takes its origins in `accept(publish: ..., consume: ...)`, where null inherits the server's origin.
+
+### Data tracks wrap a track
+
+`BroadcastProducer.publishJsonSnapshot` / `publishJsonStream`, the binary variants, and the matching consumers are gone.
+Create the track, then wrap it with `package:moq/json.dart` (or `package:moq/flate.dart` for opaque bytes).
+
+```dart
+final state = moq_json.SnapshotProducer(
+  broadcast: broadcast,
+  track: broadcast.publishTrack(name: 'state', info: null),
+  config: moq_json.SnapshotConfig(),
+);
+```
+
+### Media lives in `package:moq/media.dart`
+
+`BroadcastProducer.publishAudio`, `publishVideo`, `publishContainer`, their `OnTrack` and `Stream` variants, `setVideoProperties`, and `setCatalogSection`, and the consumer's catalog and media subscriptions, are gone, along with the `MediaProducer`, `MediaConsumer`, and `MediaGroupConsumer` aliases.
+Use `media.TrackProducer.audio` / `video`, `ContainerProducer`, `CatalogProducer`, `CatalogConsumer.subscribe`, `TrackConsumer.subscribe`, and `GroupConsumer.fetch`.
+Producers drop `name`, `used`, and `unused`; read them through `demand()`.
+
+```dart
+final audio = media.TrackProducer.audio(broadcast: broadcast, target: media.Named(null), init: init);
+```
+
+### Container byte-stream importers take an init record
+
+`media.ContainerStreamProducer` takes a `ContainerStreamInit` holding the format instead of a bare format.
+Its optional `timebase`, also on `ContainerInit`, shares one source's offset across container imports.
+Replace `format: ...` with `init: media.ContainerStreamInit(format: ...)`.
+
+### Timestamps are optional
+
+`Frame.timestampUs` and `Datagram.timestampUs` are nullable, null on a frame read from an untimed track, and so are their `timestamp` getters.
+A raw write to a timed track without a timestamp throws `TimestampMismatch` instead of going out at 0, and whole-frame media writes require one.
+`media.CatalogProducer.now()` samples the broadcast clock for local-event stamps.
+Pass `timestampUs` when writing to a timed track, and handle a null `timestamp` when reading.
+
+### Subscriber staleness is `maxDelay`
+
+`Subscription.maxAgeUs` / `maxAge` is `maxDelayUs` / `maxDelay`.
+`TrackInfo.maxAge` keeps its name: it is the publisher's retention.
+
+### Error payloads are named `reason`
+
+Exceptions that carried a positional string (`Transport`, `Internal`, `Connect`, ...) name it `reason`.
+Read `reason` instead of `v0`.
+
+### `Transport` gains `webTransport`
+
+A WebTransport session reports `MoqTransport.webTransport`; `quic` now means raw QUIC only, so an exhaustive `switch` needs one more case.
+Match `MoqTransport.webTransport` wherever you matched `MoqTransport.quic`.
+
+### `stalled` is `enabled` (#4915)
+
+`media.Video.stalled` is `enabled`, defaulting to true with the meaning inverted, and `media.Audio` gains `enabled`.
+Replace `!video.stalled` with `video.enabled`.
+
+### Routes have one cost (#4661)
+
+`MoqRoute.cold` is removed; drop the `cold` argument.
+
+### `BroadcastProducer.finish()` is removed (#4152)
+
+Call `close()` instead.

doc/bin/cli.md

@@ -62,7 +62,8 @@ each session can publish or subscribe to, including stats; see the relay's
 [statistics configuration](/bin/relay/config#stats).
 
 `moq import --help` lists the sources and `moq import rtmp --help` a specific
-one; every flag is documented there.
+one; every flag is documented there. Flags renamed between releases are listed in
+[MIGRATE.md](https://github.com/moq-dev/moq/blob/main/rs/moq-cli/MIGRATE.md).
 
 ```bash
 # Publish a file (remux to MPEG-TS without re-encoding)

doc/bin/relay/index.md

@@ -48,7 +48,9 @@ Every option is also a `--flag` or `MOQ_*` environment variable, and
 `RUST_LOG` controls logging. The
 [configuration reference](/bin/relay/config) covers every section, and
 [`demo/relay/`](https://github.com/moq-dev/moq/tree/main/demo/relay) has
-working configs for development, production, and a cluster.
+working configs for development, production, and a cluster. Options renamed
+between releases are listed in
+[MIGRATE.md](https://github.com/moq-dev/moq/blob/main/rs/moq-relay/MIGRATE.md).
 
 ## Embed
 

doc/lib/index.md

@@ -47,3 +47,8 @@ how it looks in that language:
 - **Connection stats** and **errors** that tell an auth rejection (don't retry) from a shutdown or a transport failure.
 
 C's audio decoder neither takes nor reports a playout delay.
+
+## Upgrading
+
+Each package keeps a `MIGRATE.md` saying how to migrate past every breaking
+change; [Upgrade](/setup/upgrade#migration-guides) links them all.

doc/lib/rs/moq-flate.md

@@ -32,8 +32,8 @@ an untimed track has no timescale, and a timed track requires a timestamp on
 every write. A publisher that wants to stamp now samples its own clock.
 Writes return the encoded frame size.
 
-When upgrading, replace `Timed<P, T>` with `Timed<P>` and pass capture times
-explicitly instead of relying on a write-time default.
+Upgrading from an older release: see moq-flate's
+[MIGRATE.md](https://github.com/moq-dev/moq/blob/main/rs/moq-flate/MIGRATE.md).
 
 A stream rides one group, so the whole log shares moq-net's group budget:
 32 MiB of payload and 8192 payloads. An `append` that might not fit returns

doc/lib/rs/moq-json.md

@@ -23,9 +23,8 @@ The timestamp must match the track: an untimed track has no timescale, and a
 timed track requires a timestamp on every write. Editing guards take the
 same optional capture time when opened, including when they publish on drop.
 
-When upgrading, replace `Timed<P, T>` with `Timed<P>` and pass timestamps
-explicitly. A publisher that wants to stamp an event now samples its own
-clock; the producer never supplies one.
+Upgrading from an older release: see moq-json's
+[MIGRATE.md](https://github.com/moq-dev/moq/blob/main/rs/moq-json/MIGRATE.md).
 
 A stream rides one group, so the whole log shares moq-net's group budget:
 32 MiB of payload and 8192 records. An append that might not fit is refused