Repository navigation
docs: scope branch targeting to published packages, not a crate list #3144
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
|
|
@@ -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. | ||||||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
For breaking changes to Useful? React with 👍 / 👎.
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win Include unpublished and private packages in the final shortcut. Line 16 sends -`0.0.x` means break it on `main`, anything else means `dev`.
+`0.0.x`, `publish = false`, or `private` means break it on `main`; otherwise use `dev`.📝 Committable suggestion
Suggested change
🤖 Prompt for AI Agents |
||||||
|
|
||||||
| ## Commit Messages | ||||||
|
|
||||||
|
|
||||||
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.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🔎 Supported by static analysis
🏁 Script executed:
Repository: moq-dev/moq
Length of output: 344
🏁 Script executed:
Repository: moq-dev/moq
Length of output: 11209
Describe the
0.0.xrule as project policy.Cargo and npm apply different compatibility ranges to
0.0.xversions. Replace the package-manager rationale inCONTRIBUTING.mdandCLAUDE.mdwith: “This project makes no compatibility promise for0.0.xpackages.”🤖 Prompt for AI Agents
Source: MCP tools