diff --git a/quest/m2/release/README.md b/quest/m2/release/README.md index 4ec6ee3e384..6468ecf84b2 100644 --- a/quest/m2/release/README.md +++ b/quest/m2/release/README.md @@ -30,6 +30,7 @@ production stability proven merely because upstream artifacts published. - [Migration audit](/quest/m2/release/migrate-audit.md) - the cut writes a MIGRATE.md entry for every break, stating the net published-to-final change - [API shape review](/quest/m2/release/api-review.md) - every new or changed public API reviewed for a better shape before the cut - [Feature review](/quest/m2/release/feature-review.md) - every major work line since the last release judged end to end before the cut +- [Cargo feature review](/quest/m2/release/feature-flags.md) - defaults stay lean and every remaining feature is scoped to the crate that owns it, before the cut - [Claim new npm names](/quest/m2/release/npm-first-publish.md) - a maintainer claims `@moq/clock`, `libav`, `video`, and `p2p` on npm and JSR with trusted publishing, before the cut publishes them - [Cut and publish](/quest/m2/release/cut.md) - independently executable after m1; release-triggered publication - [Published assets](/quest/m2/release/assets-release.md) - npm carries hostable worklets diff --git a/quest/m2/release/cut.md b/quest/m2/release/cut.md index 3537d7460d4..df1b39335ff 100644 --- a/quest/m2/release/cut.md +++ b/quest/m2/release/cut.md @@ -30,10 +30,11 @@ describes. This epic's remaining publication and adoption quests move to m0, the rest of m2 moves to m1, and every link to a moved path is rewritten. That PR also removes this path from every `Required`, which releases the audits waiting on it. It then re-creates this quest, the [API shape -review](/quest/m2/release/api-review.md), and the [feature -review](/quest/m2/release/feature-review.md) at the same paths under a fresh +review](/quest/m2/release/api-review.md), the [feature +review](/quest/m2/release/feature-review.md), and the [Cargo feature +review](/quest/m2/release/feature-flags.md) at the same paths under a fresh release epic in m2. Each keeps its Goal and recurrence paragraph and requires -the new `/quest/m1/README.md`, and the cut also requires both reviews. Only +the new `/quest/m1/README.md`, and the cut also requires all three reviews. Only `/quest-delete` ends the recurrence. From the 2026-10-25 pre-cut run: @@ -50,4 +51,5 @@ From the 2026-10-25 pre-cut run: - [Migration audit](/quest/m2/release/migrate-audit.md) - every break on the cut PR has its MIGRATE.md entry - [API shape review](/quest/m2/release/api-review.md) - every new or changed public API was reviewed for a better shape, and approved changes landed - [Feature review](/quest/m2/release/feature-review.md) - every major work line since the last release was judged end to end, and its follow-ups landed +- [Cargo feature review](/quest/m2/release/feature-flags.md) - every Cargo feature was judged against the feature rules, and approved changes landed - [Claim new npm names](/quest/m2/release/npm-first-publish.md) - trusted publishing can publish every new `@moq/*` package diff --git a/quest/m2/release/feature-flags.md b/quest/m2/release/feature-flags.md new file mode 100644 index 00000000000..a3bfd007266 --- /dev/null +++ b/quest/m2/release/feature-flags.md @@ -0,0 +1,64 @@ +# [M] Cargo feature review before the cut + +## Goal + +Every Cargo feature in the workspace has been judged before the release +ships. Defaults build nothing expensive or system-dependent. Each feature that +remains lives in the crate that owns its integration (`s3` in moq-archive, +forwarded by the binaries that ship it). A feature that only trims compile +time is removed in favor of always-compiled code. The scope covers the +defaults and `release` sets of shipped binaries, and the feature lists the +bindings and packaging builds pass. Each change the maintainer approves is a +quest that lands before the cut. + +## Plan + +Recurs once per major release (decided 2026-10-26). The [release +cut](/quest/m2/release/cut.md) re-creates this quest for the next release when +it shifts the milestones, so the PR finishing this run adds no successor. +Record what this run learned (inventory method, findings, what to check +first) in the cut's PR notes or a follow-up quest, so the next run starts from +it. Only `/quest-delete` ends the recurrence. + +Starts once m1 lands, so the features it reviews are the ones that ship; the +cut waits for it. Feature changes break downstream builds, which is why this +runs before the cut rather than with the post-release audits. Like the [API +shape review](/quest/m2/release/api-review.md), this run changes no code +(decided 2026-10-26): it proposes each change with a recommendation, asks the +maintainer, and files each approved change as a quest in m1, which holds the +cut until it lands. + +Judge every feature against the `# Features` rules in `rs/AGENTS.md`, and +challenge each one's premise: fewer features are better. A feature trims a +build for a few power users but fragments the code and its test matrix, so +keep one only for a vendor integration or a system dependency. For each crate, +inventory the `[features]` table, which crates forward each feature, and what +it gates. Then check: + +- Defaults: nothing that needs libclang, a system library at build or load + time, or a large dependency tree. A shipped binary's `release` set holds + every backend its platform loads without a system library. +- Scope: a vendor feature sits in the crate that integrates the vendor, and + dependents forward it under the same name instead of enabling their + dependencies' features directly. +- Fragmentation: features no consumer turns off, or that gate logic rather + than a dependency, are candidates to delete. + +What to check first (seeded 2026-10-26): + +- moq-cli's `s3`, `gcs`, and `azure` enable `object_store/aws`, `gcp`, and + `azure` directly; moq-archive, which owns storage, has no features. Also + check moq-cli's other defaults (`cluster-lan`, `quic`, `websocket`, `nvidia`) + against the rules. Distributions building with `release` is + [Ship capture and playback](/quest/m2/cli-packaging.md)'s work, not this + review's. +- The crates with the most features at seeding: moq-cli (21), moq-tokio (17), + moq-relay (14), moq-native (13), and moq-video (11). + +Related: the [compile time audit](/quest/m2/audit-compile-time.md) owns +per-crate build cost, and the [dependency audit](/quest/m2/audit-deps.md) owns +which dependencies exist. + +## Required + +- [Breaking release readiness](/quest/m1/README.md) - the release's features are final before they are reviewed diff --git a/rs/AGENTS.md b/rs/AGENTS.md index bf60f37fa98..b0ee466bad2 100644 --- a/rs/AGENTS.md +++ b/rs/AGENTS.md @@ -49,6 +49,11 @@ Prefer poll. New logic is a `poll_*` with an `async` helper, not the other way a - Append new variants to the end of a public fieldless enum with implicit discriminants; inserting reorders `as` values. - A renamed flag or env var stays as a hidden arg with its original `env`, reported by the section's `deprecated()` into `moq_tokio::cli::Deprecated`; callers must reject startup when the collection is non-empty and name the replacement rather than honor the old spelling. Never advertise the dead name in docs or `--help`. +# Features + +- Defaults skip anything expensive to build or needing a system library. Prefer fewer features: each one trims a build but fragments the code and its test matrix, so add one only for a vendor integration or a system dependency. +- A feature lives in the crate that owns the integration (`s3` in moq-archive). Dependents forward it under the same name rather than enabling their dependencies' features directly. + # Testing - Tests are inline `#[cfg(test)] mod tests`, except full Client/Server session tests over a crate's shared mock harness, which go in its `tests/integration/` module. Time-dependent async tests call `tokio::time::pause()` first (moq-net uses `#[moq_clock::test]` instead), unless they cross real networking that can't be mocked (sockets, smoke tests); those run on the wall clock and assert lower bounds.