From 6c37c34b0f955d4f1edce3269f62e50b91a2da83 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Fri, 30 Jun 2023 14:41:24 -0500 Subject: [PATCH] docs(ref): Provide guidance on version requirements I've been dealing with these situations as either the package author, depending on such a package, or supporting users who run into problems that I figure documenting this guidance in a central place means I won't have to repeat myself as often and have to re-find all of the relevant links each time. Alternatives to how this was documented - Use a regular header. All of sections in this document are flat and its hard to see association between them. This also feels like its more on the level of the "note"s. - Put this in a central Recommendations page. I think we should do something more for these when we have more (nothing else in my quick scan stood out as "recommendations" like this). At that point we can have a better idea of how it would work (much like the rule of 3 for generalizing code). I also suspect a "Recommendations" index might be better. - Put this in the FAQ. This can easily be framed as a question and we put the `Cargo.lock` policy in there. I left out talking about alternative proc-macro designs as I feel like treading new ground in community practices is out of the scope of this. See also https://rust-lang.zulipchat.com/#narrow/stream/246057-t-cargo/topic/Version.20Requirements.20documentation --- .../src/reference/specifying-dependencies.md | 37 +++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/src/doc/src/reference/specifying-dependencies.md b/src/doc/src/reference/specifying-dependencies.md index aab5aa4e8bc..8941e67ad89 100644 --- a/src/doc/src/reference/specifying-dependencies.md +++ b/src/doc/src/reference/specifying-dependencies.md @@ -107,6 +107,43 @@ Here are some examples of comparison requirements: As shown in the examples above, multiple version requirements can be separated with a comma, e.g., `>= 1.2, < 1.5`. +> **Recommendation:** When in doubt, use the default version requirement operator. +> +> In rare circumstances, a package with a "public dependency" +> (re-exports the dependency or interoperates with it in its public API) +> that is compatible with multiple semver-incompatible versions +> (e.g. only uses a simple type that hasn't changed between releases, like an `Id`) +> may support users choosing which version of the "public dependency" to use. +> In this case, a version requirement like `">=0.4, <2"` may be of interest. +> *However* users of the package will likely run into errors and need to to +> manually select a version of the "public dependency" via `cargo update` if +> they also depend on it as Cargo might pick different versions of the "public +> dependency" when [resolving dependency versions](resolver.md) (see +> [#10599]). +> +> Avoid constraining the upper bound of a version to be anything less than the +> next semver incompatible version +> (e.g. avoid `">=2.0, <2.4"`) as other packages in the dependency tree may +> require a newer version, leading to an unresolvable error (see #6584). +> Consider whether controlling the version in your [`Cargo.lock`] would be more +> appropriate. +> +> In some instances this won't matter or the benefits might outweigh the cost, including: +> - When no one else depends on your package e.g. it only has a `[[bin]]` +> - When depending on a pre-release package and wishing to avoid breaking +> changes then a fully specified `"=1.2.3-alpha.3"` might be warranted (see +> [#2222]) +> - When a library re-exports a proc-macro but the proc-macro generates code that +> calls into the re-exporting library then a fully specified `=1.2.3` might be +> warranted to ensure the proc-macro isn't newer than the re-exporting library +> and generating code that uses parts of the API that don't exist within the +> current version + +[`Cargo.lock`]: ../guide/cargo-toml-vs-cargo-lock.md +[#2222]: https://github.com/rust-lang/cargo/issues/2222 +[#6584]: https://github.com/rust-lang/cargo/issues/6584 +[#10599]: https://github.com/rust-lang/cargo/issues/10599 + ### Specifying dependencies from other registries To specify a dependency from a registry other than [crates.io], first the