docs: Dependency specification: improve description of caret requirement #8992
Conversation
| @@ -18,7 +18,7 @@ of the dependency and on the optional constraints that might be needed for it to | |||
|
|
|||
| ### Caret requirements | |||
|
|
|||
| **Caret requirements** allow [SemVer](https://semver.org/) compatible updates to a specified version. An update is allowed if the new version number does not modify the left-most non-zero digit in the major, minor, patch grouping. For instance, if we previously ran `poetry add requests@^2.13.0` and wanted to update the library and ran `poetry update requests`, poetry would update us to version `2.14.0` if it was available, but would not update us to `3.0.0`. If instead we had specified the version string as `^0.1.13`, poetry would update to `0.1.14` but not `0.2.0`. `0.0.x` is not considered compatible with any other version. | |||
| **Caret requirements** allow [SemVer](https://semver.org/) compatible updates to a specified version. An update is allowed if the new version only modifies the less significant numbers (i.e. numbers to the right of the left-most non-zero number) in the major, minor, patch grouping. For instance, if we previously ran `poetry add requests@^2.13.0` and wanted to update the library and ran `poetry update requests`, poetry would update us to version `2.14.0` if it was available, but would not update us to `3.0.0`. If instead we had specified the version string as `^0.1.13`, poetry would update to `0.1.14` but not `0.2.0`. `0.0.x` is not considered compatible with any other version. | |||
There was a problem hiding this comment.
Is "less significant" a common term? (I know "least significant" but haven't heard "less significant" before.)
Alternatively, we could just write "... only modifies the numbers to the right ...".
There was a problem hiding this comment.
For what it's worth, I've done some Google searches: "less significant numbers" yields ~38k results, "least significant number" ~61k, i.e. the former is used less but both figures have the same order of magnitude.
Strictly speaking, using "less significant numbers" on its own is incorrect, because I'm not mentioning less significant than what. However, the rationale for this phrasing is that "numbers to the right of the left-most non-zero number" is quite a mouthful that most people will need to read at least twice before understanding it; so having a less precise, more intuitive explanation first can help quickly grasp the idea before getting into the technical details.
What do you think?
|
Taking #8991 (comment) into account I'll close this since I am not very convinced myself. Even though the change might be more correct, I think it is more difficult to understand and as already mentioned in #8991 (comment) the misunderstanding feels very unlikely. Nevertheless, thanks for your efforts. |
|
This pull request has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs. |
I'm open to suggestions for improving the wording still, but I believe this version already improves the current documentation. I've included both a succinct ("the less significant numbers") and a more formal definition.
Pull Request Check List
Resolves: #8991