Why does moving a dependency from 1.x to 2.0 force a major release of a Rust library whose public function takes that dependency's `Url` type?
answer
- two majors, two different crates
- a type in your signature
- E0308 with multiple versions noted
- your major follows its major
basics
~20 sCargo can build 1.x and 2.x of one crate side by side, and their Url types are distinct. Callers passing a 1.x Url to a function now expecting the 2.0 Url get E0308, so the dependency's major bump becomes the library's.
solid answer
~50 sA **public dependency** is a crate whose types or traits appear in your public API: parameter and return types, public fields, trait impls such as `impl From<weburl::ParseError> for Error`, bounds on public generics, re-exports. Cargo treats 1.x and 2.x as incompatible and may put both in one build; each copy is a separate crate, so `weburl` 1.x's `Url` and 2.0's `Url` are unrelated types. Once your library's `pub fn get(target: weburl::Url)` is built against 2.0, a caller still constructing a 1.x `Url` gets E0308 with the note `there are multiple different versions of crate `weburl` in the dependency graph`. So your major version follows its major version. A dependency used only privately can usually be bumped in a minor release. Mitigations: keep foreign types out of the API (wrap them, or accept `&str`), and re-export the crate with `pub use weburl;` so callers can name your copy.
code
plaintext · 10 lineserror[E0308]: mismatched types
--> app/src/main.rs:3:32
|
3 | println!("{}", netlib::get(u));
| ----------- ^ expected `weburl::Url`, found `Url`
| |
| arguments to this function are incorrect
|
note: there are multiple different versions of crate `weburl` in the dependency graph
= help: you can use `cargo tree` to explore your dependency treego deeper
Recall that a type from another crate in your public function becomes part of your API.
Explain why two semver-incompatible versions of one crate give two distinct types, and how rustc's E0308 note reveals it.
Find public dependencies hiding in trait impls and bounds, and choose between wrapping, re-exporting and accepting std types.
Budget public dependencies as release-cadence commitments: each one's major bumps become yours, and none should be pre-1.0 behind a 1.0 crate.
## What makes a dependency public A crate's dependencies split into two groups: - **Private dependencies** are used only inside the implementation. Callers never see their types, so swapping or upgrading them does not change your API. - **Public dependencies** are crates whose items appear in your public API. The Rust API Guidelines define them as "crates from which types are used in the public API of the current crate". A dependency becomes public in more places than function signatures: - parameter and return types: `pub fn get(target: weburl::Url) -> usize` - public fields and enum variant payloads of the dependency's types - trait impls on your public types, in either direction: `impl From<weburl::ParseError> for Error`, or implementing the dependency's trait for your type - trait bounds on public generic items, and `pub use` re-exports The guidelines warn that public dependencies "can sneak in at unexpected places": a private error enum holding the dependency's error is fine, but a public `From` impl for it puts the dependency into the API. ## Why the dependency's major becomes yours Cargo's resolver may build **two semver-incompatible versions** of one crate into the same program (how Cargo selects versions and when duplicates appear belongs with the resolver and `Cargo.lock`). rustc sees them as **two different crates**, so `weburl` 1.x's `Url` and `weburl` 2.0's `Url` are unrelated types, however similar their definitions. Suppose your library `netlib` 1.3 exposes `pub fn get(target: weburl::Url)` and is built against `weburl` 1.x, and an application uses both `netlib` and `weburl` 2.0 directly. Passing its own `Url` fails (rustc's output, abridged): ```plaintext error[E0308]: mismatched types expected `weburl::Url`, found `Url` note: there are multiple different versions of crate `weburl` in the dependency graph ``` The same failure hits callers in the other direction when `netlib` moves to `weburl` 2.0 and the application still uses 1.x. Code that compiled against `netlib` 1.3 no longer compiles against the new release, so the upgrade is a **major** change for `netlib`, even though its own source barely changed. ## Stability is only as strong as public dependencies From this the API Guidelines draw the rule that **a crate cannot be stable (1.0.0 or later) unless all of its public dependencies are stable**. A 1.0 library exposing a 0.x crate's types inherits that crate's breaking-release cadence: every 0.y bump of the dependency forces a choice between staying on the old version and releasing a new major. ## Keeping the coupling under control | Technique | What it buys | What it costs | |---|---|---| | Accept std types (`&str`, `Duration`) and parse internally | the dependency becomes private | callers lose the typed value | | Wrap it: `pub struct Url(weburl::Url)` with your own methods | you choose what to expose | extra API to maintain | | Re-export: `pub use weburl;` | callers name exactly your copy, avoiding mismatches | your major still follows its major | | Put the integration behind an optional Cargo feature | users who do not need it are unaffected | the feature itself is public API | Re-exporting is often misread as a fix. It helps callers pick the **same** version you use, but the type is still in your API, so its next major is still your next major. Cargo also has a way to declare which dependencies are public (`public = true` on a dependency, which feeds rustc's `exported_private_dependencies` lint), but that marking is **unstable**: it needs nightly and `-Zpublic-dependency`. On stable, auditing the public API by hand or with tooling is the practical check. ## Auditing the public API - List the external paths that appear in `pub` signatures, public fields and variant payloads. - Search for `impl From<...>` and trait impls that name another crate's items. - Check bounds on public generic items, such as `T: dep::Codec`. - Check `pub use` lines, which can re-export whole crates. Each hit is a release-cadence commitment the crate should accept on purpose. ## Applied to the HTTP-client library For an HTTP client, the usual public-dependency candidates are URL, header and TLS types. Every one that appears in a signature or a trait impl ties the client's major releases to that crate's. Exposing few of them, wrapping the rest, and naming the remaining ones in the release policy turns surprise majors into planned ones.
- Does adding `pub use weburl;` to the Rust library remove the need for a major release when `weburl` goes to 2.0?No. The re-export lets callers write `netlib::weburl::Url` and so always use the same copy as the library, which avoids mismatched-version errors. But the type is still part of the library's API, so moving to `weburl` 2.0 still breaks callers that built 1.x values, and the library's major still follows its dependency's.
- Can a dependency become public in a Rust library without appearing in any function signature?Yes. A public `impl From<weburl::ParseError> for Error` puts it in the API even when the error enum holding it is private, as the Rust API Guidelines point out. Implementing the dependency's traits for your public types, bounds on public generics and `pub use` re-exports do the same.
- Bumping any dependency's major version always forces my own major release.
- Cargo always unifies 1.x and 2.x into one copy, so the types match.
- Re-exporting the dependency with pub use decouples my major version from its.
- A dependency used only inside a private enum stays private even with a public From impl.
- A 1.0 crate can expose a 0.x crate's types without weakening its stability promise.