Repository navigation
quest: plan the API changes worth making before the breaking cut #6346
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,44 @@ | ||
| # [L] API-diff check on release PRs | ||
|
|
||
| ## Goal | ||
|
|
||
| A `just` recipe diffs each published package's public API against its last | ||
| published version, and every PR into `release` runs it. A backport fails on | ||
| any break; the breaking cut PR reports the diff for the | ||
| [migration audit](/quest/m2/release/migrate-audit.md). | ||
|
|
||
| ## Plan | ||
|
|
||
| Decided 2026-10-16 (maintainer interview), split out of the migration audit | ||
| and moved to m1 on 2026-10-22 (maintainer, from an external API audit) so | ||
| the report runs locally against `main` while m1's breaks are still landing, | ||
| instead of first appearing at the cut: | ||
|
|
||
| - Commit `!` markers undercount: a 2026-10-16 sample estimated 12-15 | ||
| unmarked breaks on top of 87 marked ones, a floor since signature-only | ||
| changes escape the heuristic. This check is the backstop; PRs into `main` | ||
| get no CI check. | ||
| - Runs on PRs into `release` only: backports must keep the published API | ||
| (CONTRIBUTING), and the cut PR gets a full audit. | ||
| - Backports fail on any detected break. The cut PR only reports: Rust | ||
| versions are bumped by release-plz after the cut lands, so the diff cannot | ||
| gate on a version bump there. | ||
| - One `just` recipe, three backends: cargo-semver-checks for Rust crates, | ||
| emitted `.d.ts` API reports for `@moq/*` packages, and a `moq.h` plus | ||
| UniFFI interface diff for the bindings. Prefer maintained tools over | ||
| hand-rolled diffing. Wire it into the workflow that runs on PRs into | ||
| `release`. | ||
| - Baseline is the last published artifact, not a git tag: `@moq/*` and | ||
| `moq-rs` publish without tags. Rust compares against crates.io | ||
| (cargo-semver-checks' default), JS against the npm tarball's declarations, | ||
| and the FFI interfaces against the published `moq-ffi` crate and the last | ||
| released C archive's `moq.h`. | ||
| - Coverage: the report covers Rust crates, `@moq/*` declarations, and the | ||
| generated FFI interfaces. A break only in a hand-written binding wrapper | ||
| (`py/moq-rs`, `kt/moq`, `dart/moq`, `go/wrapper`, `swift`, `cpp/moq`, | ||
| `cpp/obs`) or a binary's flags, env vars, or config keys escapes it; the | ||
| migration audit reads those by hand. Per-language wrapper checks are out | ||
| of scope until a missed break shows they are needed. | ||
|
|
||
| Run it against `main` when it lands and put the unmarked breaks it finds in | ||
| the PR description, so their `MIGRATE.md` entries land before the cut. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,41 @@ | ||
| # [M] Binding encoders take exact rates and codec-only settings | ||
|
|
||
| ## Goal | ||
|
|
||
| A binding caller can encode 30000/1001 video exactly, and a codec-only | ||
| encoder accepts nothing it ignores. `MoqVideoEncoderInput.framerate` becomes | ||
| a rational rate instead of a `u32` the encoders turn into `Rate(n, 1)`, and | ||
| the publication `track` name leaves `MoqVideoEncoderOutput` and | ||
| `MoqAudioEncoderOutput` for options only `MoqVideoProducer::new` and | ||
| `MoqAudioProducer::new` take. | ||
|
|
||
| ## Plan | ||
|
|
||
| Decided 2026-10-22 (maintainer, from an external API audit): one quest for | ||
| both, since they break the same records and every wrapper, so callers | ||
| migrate once with the cut. | ||
|
|
||
| - Rate: `rs/moq-ffi/src/video.rs` builds `moq_video::Rate::new(framerate, 1)` | ||
| in `video_encoder_config` (the codec-only `MoqVideoEncoder`) and again | ||
| inline in `MoqVideoProducer::new`; `moq_video::Rate` already holds a | ||
| numerator and denominator. Expose it as a numerator/denominator record and | ||
| build the rate once. Audio's integer `sample_rate` is exact and stays. | ||
| - Publication options: `track` is the only publish-only field today. | ||
| `video_encoder_config` and `audio_settings` never read it. Nest it in a | ||
| publication options record taken by the producers, beside the existing | ||
| `catalog` and `bandwidth` arguments, rather than adding a fourth argument. | ||
| Keep the `audio`/`video` namespaces. Propose the record and field names | ||
| with a recommendation in the PR before shipping them. | ||
| - Wrappers alias the uniffi records, so update `py/moq-rs`, `kt/moq`, | ||
| `swift`, `dart/moq`, `go/wrapper`, `cpp/moq`, their tests and `doc/lib/*` | ||
| per the Cross-Package Sync table. The generated C picks the records up; | ||
| the hand-written `rs/moq-c` has no raw encoder, so it is untouched. | ||
| - [OBS moq-video adapter](/quest/m2/obs-moq-video/adapter.md) later adds a | ||
| preset to the codec-only config; this shape is the one it extends. | ||
|
|
||
| Public API: breaking in moq-ffi and every binding wrapper, each with a | ||
| `MIGRATE.md` entry. Wire: none. | ||
|
Comment on lines
+36
to
+37
There was a problem hiding this comment.
Because this quest explicitly includes Useful? React with 👍 / 👎. |
||
|
|
||
| ## Related | ||
|
|
||
| - [Exact timestamps in every binding](/quest/m1/binding-timestamps.md) - the other exact-time break to the same bindings in this cut | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
When this quest is implemented, both
MoqVideoProducer::newandMoqAudioProducer::newalready take four arguments:catalog,input,output, andbandwidth. Placing a new publication-options record beside the existing catalog and bandwidth arguments would therefore create a fifth argument, despite the plan claiming this avoids adding a fourth. Clarify which existing arguments the record absorbs so the planned API can satisfy the repository's argument-count rule.AGENTS.md reference: AGENTS.md:L68-L69
Useful? React with 👍 / 👎.