Specifying dependencies: add exact version section #9961

marcospb19 · 2021-10-05T01:25:27Z

Specifying exact versions is extremely useful, I gave it a dedicated section separating from the "Comparison requirements" one, even tho it can be mixed up with comparison requirements.

Specify an exact version together with other comparison requirements seems to be redundant:

time = "= 0.3.3, > 0.2.0"
rand = "= 0.8.3, >= 0.8.3, < 0.8.4"

It's redundant because it can only solve to "0.3.3" and "0.8.3".

Questions:

Is it ok to separate these sections?
Should I add a note in the Exact version requirement section saying that it can be chained with other Comparison requirements? (even if it's useless)

I would suggest separating it and adding a new warning for when this occurs, saying that it is redundant (I also would like to implement it).

In [dependencies] a "=" can be used to specify an exact version

rust-highfive · 2021-10-05T01:25:30Z

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @alexcrichton (or someone else) soon.

Please see the contribution instructions for more information.

alexcrichton · 2021-10-05T14:37:33Z

Thanks for the PR! I think it's fine to split this out to its own section, although strict version requirements like this are generally an anti-pattern on crates.io itself so we tend to advise against it, so could the section be placed at the end instead of the front? (if you're up for it calling out the hazards of publishing a crate with strict version requirements would also be great). Otherwise though I think it might be good to say that multiple requirements can be listed (I thought they needed to be separated with , but maybe not?), but I don't think there's any need to call out specifically that for =foo requirements specifying other things may not make much sense.

Rewrote sections about specifying dependencies versions in Cargo.toml

marcospb19 · 2021-10-07T10:39:21Z

I thought they needed to be separated with , but maybe not?

Oh yes, they do, sorry, I edited the original message

rand = "= 0.8.3, >= 0.8.3, < 0.8.4"

marcospb19 · 2021-10-07T10:41:51Z

Oops, I tried renaming the branch, that closed the PR unintentionally.

marcospb19 · 2021-10-07T10:48:35Z

@alexcrichton I tried to rewrite all the version requirements sections, they were untouched for more than 4 years.

I said that using strict version requirements would be redundant with other requirements, however, there is this counter-example:

time = "=0.3, < 0.3.5"
# which is equivalent to
time = ">=0.3, < 0.3.5"
# and
time = ">=0.3.0, < 0.3.5"

marcospb19 · 2021-10-07T10:50:37Z

src/doc/src/reference/specifying-dependencies.md

+> **Note**: Using strict requirements with exact versions are a bad practice and
+> should be avoided, as it disables the ability of receiving important patches
+> of security, soundness and bugfixes.


Here is the advice you suggested, about the hazard of using strict requirements.

I would not word this so strongly. This goes against the advice given in https://doc.rust-lang.org/cargo/reference/resolver.html#recommendations where exact requirements do have some use cases (for example, serde has an exact semver requirement on serde_derive because the two are very tightly coupled and not intended to be used independently.

There are other use cases, such as a temporary workaround to lock to an exact version. I think we've done that with cargo itself before.

Changed it to:

> **Note**: When using strict requirements with exact versions, no updates can > be applied, including bugfixes and security updates.

Any other recommendations?

marcospb19 · 2021-10-07T10:52:41Z

src/doc/src/reference/specifying-dependencies.md

-[semver]: https://github.com/steveklabnik/semver#requirements
+[semver]: https://github.com/dtolnay/semver


Unresolved question: where was this pointing to? The previous repository now leads to this new one I inserted, but there is no section "#requirements".

I think it used to summarize the rules for requirements, but that has been removed and instead points to this page (somewhat circular).

I notice this page doesn't link to or describe what SemVer is anywhere. Perhaps it could link to https://semver.org/ and/or https://doc.rust-lang.org/cargo/reference/resolver.html#semver-compatibility?

Changed it to https://doc.rust-lang.org/cargo/reference/resolver.html#semver-compatibility, because it already points to https://semver.org/ in the first line.

So it's like we're pointing to both.

ehuss

Thanks for the PR!

Lots of comments, but only because I think this text can be really important to be as clear as possible.

ehuss · 2021-10-07T14:51:25Z

src/doc/src/reference/specifying-dependencies.md

+If we specify the version string as `"1.0.4"`, compatible versions are, `1.0.x`
+where `x` is greater than 4.


I don' tthink this is correct. Specifying "1.0.4" means that it will pick any version 1.x.y greater than 1.0.4.

I find this to be a bit hard to explain without being confusing and verbose.

I tried organizing this in another way, here's what I came up with:

If we specify the version string as `"1.4.8"`, compatible versions are: - `"1.4.x"` with `x ≥ 8`. - `"1.x.y"` with `x > 2`, `y` can be anything.

What do you think?

ehuss · 2021-10-07T14:57:22Z

src/doc/src/reference/specifying-dependencies.md

-separated with a comma, e.g., `>= 1.2, < 1.5`.
+As shown in the examples above, it is possible to combine any requirements to
+restrict the version even further, however, this is only necessary with
+[comparison requirements](#Comparison-requirements).


Section fragments should be in lower case.

Suggested change

[comparison requirements](#Comparison-requirements).

[comparison requirements](#comparison-requirements).

Also, I would maybe include what it means to combine requirements, both the syntax and the semantics. That is, saying that you can combine multiple requirements with commas, and that it means that all requirements must be met.

Fixed the section upper case and added this text to the multiple requirements part:

The list of requirements should be separated by commas, spaces are optional. A version is considered to be compatible with the list only if it is compatible with all elements of the list.

ehuss · 2021-10-07T15:19:18Z

src/doc/src/reference/specifying-dependencies.md

+> **Note**: Using strict requirements with exact versions are a bad practice and
+> should be avoided, as it disables the ability of receiving important patches
+> of security, soundness and bugfixes.


I would not word this so strongly. This goes against the advice given in https://doc.rust-lang.org/cargo/reference/resolver.html#recommendations where exact requirements do have some use cases (for example, serde has an exact semver requirement on serde_derive because the two are very tightly coupled and not intended to be used independently.

There are other use cases, such as a temporary workaround to lock to an exact version. I think we've done that with cargo itself before.

ehuss · 2021-10-07T15:21:52Z

src/doc/src/reference/specifying-dependencies.md

+You can specify different dependencies for:
+- Development and release profiles.


I'm not sure what is meant is meant here, but it seems to imply you can independently define dependencies for different profiles (which can't be done). Can you say why this is mentioning profiles here?

I was mistaken in this one, glad you got my mistake in the review.

Rewritten to:

Dependencies can be specified for [crate features](features.md) and for different [architectures and operating systems](#platform-specific-dependencies).

ehuss · 2021-10-07T15:24:18Z

src/doc/src/reference/specifying-dependencies.md

-[semver]: https://github.com/steveklabnik/semver#requirements
+[semver]: https://github.com/dtolnay/semver


I think it used to summarize the rules for requirements, but that has been removed and instead points to this page (somewhat circular).

I notice this page doesn't link to or describe what SemVer is anywhere. Perhaps it could link to https://semver.org/ and/or https://doc.rust-lang.org/cargo/reference/resolver.html#semver-compatibility?

ehuss · 2021-10-07T15:36:27Z

src/doc/src/reference/specifying-dependencies.md

+**Caret requirements** allow SemVer compatible updates, it's the only
+requirement type that uses specific rules for versions with and without the zero
+digits.


I'm a bit confused by this statement about the zero digits.

Usually I think it is best to have a definition up front when introducing a term, and I think it would be good to lead with the sentences that define its left-most non-zero behavior. I think the wording here is very important since this is introducing a potentially confusing topic, and this is one of the most important parts of cargo. If possible, it would be best to try to approach it assuming you don't know what semver is, or what a version requirement is and what it means. The original text tried to do that by introducing a topic by example from the perspective of what someone does with these dependencies. I'm not saying it has to use that style, just mentioning that is one way to introduce a new concept.

Ok, I rewrote this section and now the definition comes first, needs another review.

src/doc/src/reference/specifying-dependencies.md

ehuss · 2021-10-07T16:00:49Z

src/doc/src/reference/specifying-dependencies.md

+
+### Strict version requirements
+
+**Strict version requirements** allow you to lock the numbers for major, minor


I'm a little uneasy introducing this as a separately defined kind of requirement. For example =1 is not what I would characterize as "strict". Is there a particular reason for adding it? It seems like it fits with the comparison section, as = is a comparison operator.

My reasoning was that strict requirements only unique purpose is specifying exact versions without having to create a list of multiple requirements.

For example, =1.2.3 is a shorthand for >= 1.2.3, < 1.2.4.

And the other comparison operators all leave open ranges to be combined with more operators, = on the other hand, works very similarly to *, specifying a part of the version, and having the missing parts be "anything".

bors · 2021-12-05T16:44:24Z

☔ The latest upstream changes (presumably #10158) made this pull request unmergeable. Please resolve the merge conflicts.

ehuss · 2021-12-14T17:46:29Z

Ping @marcospb19 Just checking in to see if you are still interested in working on this, or if you had any questions.

marcospb19 · 2021-12-14T23:38:20Z

I'm still interested!

Sorry for the delay, I've been struggling finding time between multiple projects.

Now seems like a better time for trying finishing it, I'll see if I can take a look.

Thanks for the ping :D .

marcospb19 · 2021-12-17T04:46:48Z

Working on the conflict now.

marcospb19 · 2021-12-17T05:08:10Z

About the conflicts, some smaller work were done in the second section of this document in order to improve some of the explanations, I reused the new texts added there, but kept the new section organization that was made in this PR, containing the table of all operators and keeping the Caret Requirement explanation inside of it's dedicated section.

src/doc/src/reference/specifying-dependencies.md

alexcrichton · 2021-12-20T16:31:52Z

src/doc/src/reference/specifying-dependencies.md

+
+> **Note**: This is the only type of version requirement that has different
+> rules for versions that start with `0`, and the version `"0.x.y"` is not
+> compatible with any other versions.


I'm not sure I understand this last clause about 0.x.y not being compatible with anything else, isn't 0.x.(y+1) compatible with that?

Yes, if x > 0.

Before the review this was stating that 0.0.x was not compatible with other versions, @ehuss said that 0.0.x was not a common version, so it wouldn't be as useful in this explanation, so I changed to 0.x.y without noticing that it is now incorrect.

I'm not sure how to proceed here, is this information even useful? I do often get confused about this, maybe I should just leave the definition.

Or remove completely the "and" part?

, and the version "0.x.y" is not compatible with any other versions.

What is this note trying to convey? It's correct that 0.0.x is not that common but it's incorrect to say that 0.x.y is not compatible with any other versions.

weihanglo · 2021-12-20T17:09:18Z

src/doc/src/reference/specifying-dependencies.md

+^1      :=  >=1.0.0, <2.0.0
+^1.2    :=  >=1.2.0, <2.0.0
+^1.2.3  :=  >=1.2.3, <2.0.0
+^0      :=  >=0.0.0, <1.0.0
+^0.0    :=  >=0.0.0, <0.1.0
+^0.0.3  :=  >=0.0.3, <0.0.4 (exact)
+^0.2    :=  >=0.2.0, <0.3.0
+^0.2.3  :=  >=0.2.3, <0.3.0


IIUC #10158 tried not to mention much about the ^ syntax on requirement to reduce confusion. Do we want to follow the rule here and throughout this PR?

How could I proceed here?

Rename caret requirement to SemVer requirement.

Inside of the caret requirements section, remove all carets, and add a note explaining that "1.4.8" == "^1.4.8".

Try to move all caret requirements out of it's own section, and put it on the start of the file.

I tried approaching 3 like #10158 but I found it to be weird with the new table with all the operators.

Hmm... maybe keep calling it caret but only mention it as a alternative syntax at the end of the "Caret requirements" section? Such like

Note that Cargo favors specifying caret requirements without a real caret ^. You can still use the alternative syntax. For example, ^1.2.3 is exactly equivalent to 1.2.3.

Though it still seems a bit awkward...

I like @weihanglo's idea here to not use ^ in this section where possible, and at the end there can be a small code-block that says that ^1.2.3 := 1.2.3 or similar

ehuss · 2022-03-22T17:49:01Z

I'm going to close due to inactivity. If you or anyone is interested in continuing this, feel free to open a new PR with the above comments addressed.

Specifying dependencies: add exact version section

0d1e996

In [dependencies] a "=" can be used to specify an exact version

rust-highfive assigned alexcrichton Oct 5, 2021

rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Oct 5, 2021

Review first sections of specifying-dependencies

8570807

Rewrote sections about specifying dependencies versions in Cargo.toml

marcospb19 closed this Oct 7, 2021

marcospb19 deleted the patch-1 branch October 7, 2021 10:40

marcospb19 restored the patch-1 branch October 7, 2021 10:40

marcospb19 reopened this Oct 7, 2021

marcospb19 commented Oct 7, 2021

View reviewed changes

ehuss reviewed Oct 7, 2021

View reviewed changes

ehuss added S-waiting-on-author Status: The marked PR is awaiting some action (such as code changes) from the PR author. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Oct 25, 2021

marcospb19 requested a review from ehuss December 17, 2021 04:28

marcospb19 force-pushed the patch-1 branch from 1af3166 to 7bd4e4a Compare December 17, 2021 04:46

marcospb19 added 2 commits December 17, 2021 01:57

rust-lang#9961 review iteration 1 (commit shall be rebased)

2e44eae

Improving table contents indentation for readibilty

72f8c56

marcospb19 force-pushed the patch-1 branch from 7bd4e4a to 72f8c56 Compare December 17, 2021 05:01

Merge branch 'master' into patch-1

c59cb1a

marcospb19 added 2 commits December 17, 2021 02:12

Rename "Strict version requirements" to "Strict requirements"

c311f5f

Adding navigation links to table of requirement types

b8bff19

alexcrichton reviewed Dec 20, 2021

View reviewed changes

weihanglo reviewed Dec 20, 2021

View reviewed changes

Fix typo

8d060be

alexcrichton removed their assignment Mar 8, 2022

ehuss closed this Mar 22, 2022

		[semver]: https://github.com/steveklabnik/semver#requirements
		[semver]: https://github.com/dtolnay/semver

		If we specify the version string as `"1.0.4"`, compatible versions are, `1.0.x`
		where `x` is greater than 4.

	[comparison requirements](#Comparison-requirements).
	[comparison requirements](#comparison-requirements).

		You can specify different dependencies for:
		- Development and release profiles.


		### Strict version requirements

		Strict version requirements allow you to lock the numbers for major, minor

Specifying dependencies: add exact version section #9961

Specifying dependencies: add exact version section #9961

Conversation

marcospb19 commented Oct 5, 2021 • edited Loading

rust-highfive commented Oct 5, 2021

alexcrichton commented Oct 5, 2021

marcospb19 commented Oct 7, 2021

marcospb19 commented Oct 7, 2021 • edited Loading

marcospb19 commented Oct 7, 2021

marcospb19 Oct 7, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ehuss left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

marcospb19 Dec 17, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

marcospb19 Dec 17, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

marcospb19 Dec 17, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bors commented Dec 5, 2021

ehuss commented Dec 14, 2021

marcospb19 commented Dec 14, 2021

marcospb19 commented Dec 17, 2021

marcospb19 commented Dec 17, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ehuss commented Mar 22, 2022

marcospb19 commented Oct 5, 2021 •

edited

Loading

marcospb19 commented Oct 7, 2021 •

edited

Loading

marcospb19 Oct 7, 2021 •

edited

Loading

marcospb19 Dec 17, 2021 •

edited

Loading

marcospb19 Dec 17, 2021 •

edited

Loading

marcospb19 Dec 17, 2021 •

edited

Loading