diff --git a/CLAUDE.md b/CLAUDE.md index 214887e886e..73178ed4cf0 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -212,7 +212,7 @@ For wire, `moq-ffi`, or gateway changes, also run the cross-language interop mat ## Branch Targeting -PRs target `main` by default, however large the change: bug fixes, new behavior, additive APIs, docs, refactors, and wire-protocol work. `dev` is reserved for one thing, a semver break in a published API: a renamed, removed, or signature-changed `pub`/exported item in the core libraries or language wrappers. Adding an item is additive, so it goes to `main`. When in doubt, target `main`. Full rules in [CONTRIBUTING.md](CONTRIBUTING.md#branch-targeting). +PRs target `main` by default, however large the change: bug fixes, new behavior, additive APIs, docs, refactors, and wire-protocol work. `dev` is reserved for one thing, a semver break in a published API: a renamed, removed, or signature-changed `pub`/exported item, or anything else that stops existing caller code compiling, in any package someone can depend on a released version of. Adding an item is additive, so it goes to `main`. `0.0.x` packages are exempt, since every `0.0.x` release is already its own incompatible version, so break those on `main` too. Check the version, not the crate name. Full rules in [CONTRIBUTING.md](CONTRIBUTING.md#branch-targeting). ## Workflow diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index da97feaec27..bfe3dba9297 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -9,11 +9,15 @@ Two long-lived branches. The split is about **semver breakage of a published API - **`main`**: the default. Bug fixes, new behavior, new/additive APIs, docs, and refactors that preserve the existing public API. A change that only *adds* is additive and lands here even when it is big: a new `pub` item, a new option, or a parser accepting a broader set of inputs it previously rejected. Changing what a component does with input it *already* takes (e.g. recognizing a media pattern it used to mishandle) is a fix, not a break, so it also lands here. Wire-protocol and format work lands here too, including `moq-lite` / `moq-transport` framing, a new draft version, a field added to or removed from an in-progress one, and catalog/container format changes in `rs/hang` or `js/hang`. Versions are negotiated per session, so a peer keeps speaking whatever version it already supports; the change reaches it only once both ends offer the new one. Ship it behind a version gate (see the Version matching section of [`rs/CLAUDE.md`](rs/CLAUDE.md)) and update the matching draft under `drafts/` in the same PR. -- **`dev`**: reserved for changes that violate semver by breaking a published API. That means a renamed, removed, or signature-changed `pub` (Rust) or exported (TS) item in `rs/moq-net`, `rs/hang`, `rs/moq-ffi`, `rs/libmoq`, `js/net`, `js/hang`, or any of the language wrappers under `swift/`, `kt/`, `go/`, `py/`. A newly *added* item is additive and goes to `main`. +- **`dev`**: reserved for changes that violate semver by breaking a published API. That means a renamed, removed, or signature-changed `pub` (Rust) or exported (TS) item, or anything else that stops existing caller code compiling, such as adding a field to a struct consumers build with a literal. A newly *added* item is additive and goes to `main`. + + This covers **every package someone can depend on a released version of**, not a shortlist of the well-known ones: the `rs/` crates release-plz publishes, the `@moq/*` packages under `js/`, and the language wrappers under `swift/`, `kt/`, `go/`, `py/`. `libmoq` counts through its C ABI too, so a `moq.h` break is a `dev` change even though nothing depends on the crate. + + **`0.0.x` packages are the exception: break them on `main`.** Cargo and npm treat every `0.0.x` release as its own incompatible version, so such a package makes no compatibility promise and has no contract to violate. That covers `moq-audio`, `moq-video`, `moq-transcode`, and `moq-nvenc` today. The same goes for anything marked `publish = false` or `private` (`moq-bench`, `moq-wasm`, `@moq/wasm`, `@moq/clock`), which isn't published at all. Reshape their surface freely, and prefer doing so before a package leaves `0.0.x`, since that is the last cheap moment to fix a shape. A wire change usually needs no API break to land, since the version gate is internal. If yours does, that break is what sends the PR to `dev`, not the wire change itself. -`dev` periodically merges into `main` (or vice versa) when the batch is ready to ship. When in doubt, target `main`; reviewers will redirect to `dev` if a change turns out to break a published API. CI (`pull_request:` workflows) runs on PRs against either branch, so no extra setup is needed when you switch the base. +`dev` periodically merges into `main` (or vice versa) when the batch is ready to ship. When in doubt, check the package's version before its name: `0.0.x` means break it on `main`, anything else means `dev`. Reviewers will redirect a PR that turns out to break a published API. CI (`pull_request:` workflows) runs on PRs against either branch, so no extra setup is needed when you switch the base. ## Commit Messages