Auto merge of #12323 - epage:version, r=weihanglo

docs(ref): Provide guidance on version requirements

### What does this PR try to resolve?

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.

### How should we test and review this PR?

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.

### Additional information

See also https://rust-lang.zulipchat.com/#narrow/stream/246057-t-cargo/topic/Version.20Requirements.20documentation

Author: bors

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