Skip to content

Commit 6b032af

Browse files
weihangloweihanglo
committed
doc(yank): make versions have major parts
1 parent 1ccbdae commit 6b032af

File tree

4 files changed

+92
-92
lines changed

4 files changed

+92
-92
lines changed

‎src/doc/man/cargo-yank.md

Lines changed: 23 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -27,26 +27,26 @@ current directory.
2727

2828
### How yank works
2929

30-
For example, the `foo` crate published version `0.22.0` and another crate `bar`
31-
declared a dependency on version `foo = 0.22`. Now `foo` releases a new, but
32-
not semver compatible, version `0.23.0`, and finds a critical issue with `0.22.0`.
33-
If `0.22.0` is yanked, no new project or checkout without an existing lockfile will be
34-
able to use crate `bar` as it relies on `0.22`.
35-
36-
In this case, the maintainers of `foo` should first publish a semver compatible version
37-
such as `0.22.1` prior to yanking `0.22.0` so that `bar` and all projects that depend
38-
on `bar` will continue to work.
39-
40-
As another example, consider a crate `bar` with published versions `0.22.0`, `0.22.1`,
41-
`0.22.2`, `0.23.0` and `0.24.0`. The following table identifies the versions
42-
cargo could use in the absence of a lockfile for different SemVer requirements,
43-
following a given release being yanked:
44-
45-
| Yanked Version / SemVer requirement | `bar = "0.22.0"` | `bar = "=0.22.0"` | `bar = "0.23.0"` |
46-
|-------------------------------------|-------------------------------------------|-------------------|------------------|
47-
| `0.22.0` | Use either `0.22.1` or `0.22.2` | **Return Error** | Use `0.23.0` |
48-
| `0.22.1` | Use either `0.22.0` or `0.22.2` | Use `0.22.0` | Use `0.23.0` |
49-
| `0.23.0` | Use either `0.22.0`, `0.21.0` or `0.22.2` | Use `0.22.0` | **Return Error** |
30+
For example, the `foo` crate published version `1.5.0` and another crate `bar`
31+
declared a dependency on version `foo = "1.5"`. Now `foo` releases a new, but
32+
not semver compatible, version `2.0.0`, and finds a critical issue with `1.5.0`.
33+
If `1.5.0` is yanked, no new project or checkout without an existing lockfile
34+
will be able to use crate `bar` as it relies on `1.5`.
35+
36+
In this case, the maintainers of `foo` should first publish a semver compatible
37+
version such as `1.5.1` prior to yanking `1.5.0` so that `bar` and all projects
38+
that depend on `bar` will continue to work.
39+
40+
As another example, consider a crate `bar` with published versions `1.5.0`,
41+
`1.5.1`, `1.5.2`, `2.0.0` and `3.0.0`. The following table identifies the
42+
versions cargo could use in the absence of a lockfile for different SemVer
43+
requirements, following a given release being yanked:
44+
45+
| Yanked Version / SemVer requirement | `bar = "1.5.0"` | `bar = "=1.5.0"` | `bar = "2.0.0"` |
46+
|-------------------------------------|-----------------------------------------|------------------|------------------|
47+
| `1.5.0` | Use either `1.5.1` or `1.5.2` | **Return Error** | Use `2.0.0` |
48+
| `1.5.1` | Use either `1.5.0` or `1.5.2` | Use `1.5.0` | Use `2.0.0` |
49+
| `2.0.0` | Use either `1.5.0`, `1.5.1` or `0.22.2` | Use `1.5.0` | **Return Error** |
5050

5151
### When to yank
5252

@@ -58,8 +58,9 @@ typically a less disruptive mechanism to inform users and encourage them to
5858
upgrade, and avoids the possibility of significant downstream disruption
5959
irrespective of susceptibility to the vulnerability in question.
6060

61-
A common workflow is to yank a crate having already published a semver compatible version,
62-
to reduce the probability of preventing dependent crates from compiling.
61+
A common workflow is to yank a crate having already published a semver
62+
compatible version, to reduce the probability of preventing dependent
63+
crates from compiling.
6364

6465
## OPTIONS
6566

‎src/doc/man/generated_txt/cargo-yank.txt

Lines changed: 22 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -24,34 +24,34 @@ DESCRIPTION
2424
the current directory.
2525

2626
How yank works
27-
For example, the foo crate published version 0.22.0 and another crate
28-
bar declared a dependency on version foo = 0.22. Now foo releases a new,
29-
but not semver compatible, version 0.23.0, and finds a critical issue
30-
with 0.22.0. If 0.22.0 is yanked, no new project or checkout without an
31-
existing lockfile will be able to use crate bar as it relies on 0.22.
27+
For example, the foo crate published version 1.5.0 and another crate bar
28+
declared a dependency on version foo = "1.5". Now foo releases a new,
29+
but not semver compatible, version 2.0.0, and finds a critical issue
30+
with 1.5.0. If 1.5.0 is yanked, no new project or checkout without an
31+
existing lockfile will be able to use crate bar as it relies on 1.5.
3232

3333
In this case, the maintainers of foo should first publish a semver
34-
compatible version such as 0.22.1 prior to yanking 0.22.0 so that bar
35-
and all projects that depend on bar will continue to work.
34+
compatible version such as 1.5.1 prior to yanking 1.5.0 so that bar and
35+
all projects that depend on bar will continue to work.
3636

37-
As another example, consider a crate bar with published versions 0.22.0,
38-
0.22.1, 0.22.2, 0.23.0 and 0.24.0. The following table identifies the
37+
As another example, consider a crate bar with published versions 1.5.0,
38+
1.5.1, 1.5.2, 2.0.0 and 3.0.0. The following table identifies the
3939
versions cargo could use in the absence of a lockfile for different
4040
SemVer requirements, following a given release being yanked:
4141

42-
+-----------------------+-----------------------+-----------+----------+
43-
| Yanked Version / | bar = "0.22.0" | bar = | bar = |
44-
| SemVer requirement | | "=0.22.0" | "0.23.0" |
45-
+-----------------------+-----------------------+-----------+----------+
46-
| 0.22.0 | Use either 0.22.1 or | Return | Use |
47-
| | 0.22.2 | Error | 0.23.0 |
48-
+-----------------------+-----------------------+-----------+----------+
49-
| 0.22.1 | Use either 0.22.0 or | Use | Use |
50-
| | 0.22.2 | 0.22.0 | 0.23.0 |
51-
+-----------------------+-----------------------+-----------+----------+
52-
| 0.23.0 | Use either 0.22.0, | Use | Return |
53-
| | 0.21.0 or 0.22.2 | 0.22.0 | Error |
54-
+-----------------------+-----------------------+-----------+----------+
42+
+------------------------+----------------------+----------+----------+
43+
| Yanked Version / | bar = "1.5.0" | bar = | bar = |
44+
| SemVer requirement | | "=1.5.0" | "2.0.0" |
45+
+------------------------+----------------------+----------+----------+
46+
| 1.5.0 | Use either 1.5.1 or | Return | Use |
47+
| | 1.5.2 | Error | 2.0.0 |
48+
+------------------------+----------------------+----------+----------+
49+
| 1.5.1 | Use either 1.5.0 or | Use | Use |
50+
| | 1.5.2 | 1.5.0 | 2.0.0 |
51+
+------------------------+----------------------+----------+----------+
52+
| 2.0.0 | Use either 1.5.0, | Use | Return |
53+
| | 1.5.1 or 0.22.2 | 1.5.0 | Error |
54+
+------------------------+----------------------+----------+----------+
5555

5656
When to yank
5757
Crates should only be yanked in exceptional circumstances, for example,
@@ -169,4 +169,3 @@ EXAMPLES
169169

170170
SEE ALSO
171171
cargo(1), cargo-login(1), cargo-publish(1)
172-

‎src/doc/src/commands/cargo-yank.md

Lines changed: 20 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -27,26 +27,26 @@ current directory.
2727

2828
### How yank works
2929

30-
For example, the `foo` crate published version `0.22.0` and another crate `bar`
31-
declared a dependency on version `foo = 0.22`. Now `foo` releases a new, but
32-
not semver compatible, version `0.23.0`, and finds a critical issue with `0.22.0`.
33-
If `0.22.0` is yanked, no new project or checkout without an existing lockfile will be
34-
able to use crate `bar` as it relies on `0.22`.
35-
36-
In this case, the maintainers of `foo` should first publish a semver compatible version
37-
such as `0.22.1` prior to yanking `0.22.0` so that `bar` and all projects that depend
38-
on `bar` will continue to work.
39-
40-
As another example, consider a crate `bar` with published versions `0.22.0`, `0.22.1`,
41-
`0.22.2`, `0.23.0` and `0.24.0`. The following table identifies the versions
42-
cargo could use in the absence of a lockfile for different SemVer requirements,
43-
following a given release being yanked:
44-
45-
| Yanked Version / SemVer requirement | `bar = "0.22.0"` | `bar = "=0.22.0"` | `bar = "0.23.0"` |
46-
|-------------------------------------|-------------------------------------------|-------------------|------------------|
47-
| `0.22.0` | Use either `0.22.1` or `0.22.2` | **Return Error** | Use `0.23.0` |
48-
| `0.22.1` | Use either `0.22.0` or `0.22.2` | Use `0.22.0` | Use `0.23.0` |
49-
| `0.23.0` | Use either `0.22.0`, `0.21.0` or `0.22.2` | Use `0.22.0` | **Return Error** |
30+
For example, the `foo` crate published version `1.5.0` and another crate `bar`
31+
declared a dependency on version `foo = "1.5"`. Now `foo` releases a new, but
32+
not semver compatible, version `2.0.0`, and finds a critical issue with `1.5.0`.
33+
If `1.5.0` is yanked, no new project or checkout without an existing lockfile
34+
will be able to use crate `bar` as it relies on `1.5`.
35+
36+
In this case, the maintainers of `foo` should first publish a semver compatible
37+
version such as `1.5.1` prior to yanking `1.5.0` so that `bar` and all projects
38+
that depend on `bar` will continue to work.
39+
40+
As another example, consider a crate `bar` with published versions `1.5.0`,
41+
`1.5.1`, `1.5.2`, `2.0.0` and `3.0.0`. The following table identifies the
42+
versions cargo could use in the absence of a lockfile for different SemVer
43+
requirements, following a given release being yanked:
44+
45+
| Yanked Version / SemVer requirement | `bar = "1.5.0"` | `bar = "=1.5.0"` | `bar = "2.0.0"` |
46+
|-------------------------------------|-----------------------------------------|------------------|------------------|
47+
| `1.5.0` | Use either `1.5.1` or `1.5.2` | **Return Error** | Use `2.0.0` |
48+
| `1.5.1` | Use either `1.5.0` or `1.5.2` | Use `1.5.0` | Use `2.0.0` |
49+
| `2.0.0` | Use either `1.5.0`, `1.5.1` or `0.22.2` | Use `1.5.0` | **Return Error** |
5050

5151
### When to yank
5252

‎src/etc/man/cargo-yank.1

Lines changed: 27 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -24,57 +24,57 @@ or using \fBcargo\-login\fR(1).
2424
If the crate name is not specified, it will use the package name from the
2525
current directory.
2626
.SS "How yank works"
27-
For example, the \fBfoo\fR crate published version \fB0.22.0\fR and another crate \fBbar\fR
28-
declared a dependency on version \fBfoo = 0.22\fR\&. Now \fBfoo\fR releases a new, but
29-
not semver compatible, version \fB0.23.0\fR, and finds a critical issue with \fB0.22.0\fR\&.
30-
If \fB0.22.0\fR is yanked, no new project or checkout without an existing lockfile will be
31-
able to use crate \fBbar\fR as it relies on \fB0.22\fR\&.
32-
.sp
33-
In this case, the maintainers of \fBfoo\fR should first publish a semver compatible version
34-
such as \fB0.22.1\fR prior to yanking \fB0.22.0\fR so that \fBbar\fR and all projects that depend
35-
on \fBbar\fR will continue to work.
36-
.sp
37-
As another example, consider a crate \fBbar\fR with published versions \fB0.22.0\fR, \fB0.22.1\fR,
38-
\fB0.22.2\fR, \fB0.23.0\fR and \fB0.24.0\fR\&. The following table identifies the versions
39-
cargo could use in the absence of a lockfile for different SemVer requirements,
40-
following a given release being yanked:
27+
For example, the \fBfoo\fR crate published version \fB1.5.0\fR and another crate \fBbar\fR
28+
declared a dependency on version \fBfoo = "1.5"\fR\&. Now \fBfoo\fR releases a new, but
29+
not semver compatible, version \fB2.0.0\fR, and finds a critical issue with \fB1.5.0\fR\&.
30+
If \fB1.5.0\fR is yanked, no new project or checkout without an existing lockfile
31+
will be able to use crate \fBbar\fR as it relies on \fB1.5\fR\&.
32+
.sp
33+
In this case, the maintainers of \fBfoo\fR should first publish a semver compatible
34+
version such as \fB1.5.1\fR prior to yanking \fB1.5.0\fR so that \fBbar\fR and all projects
35+
that depend on \fBbar\fR will continue to work.
36+
.sp
37+
As another example, consider a crate \fBbar\fR with published versions \fB1.5.0\fR,
38+
\fB1.5.1\fR, \fB1.5.2\fR, \fB2.0.0\fR and \fB3.0.0\fR\&. The following table identifies the
39+
versions cargo could use in the absence of a lockfile for different SemVer
40+
requirements, following a given release being yanked:
4141

4242
.TS
4343
allbox tab(:);
4444
lt lt lt lt.
4545
T{
4646
Yanked Version / SemVer requirement
4747
T}:T{
48-
\fBbar = "0.22.0"\fR
48+
\fBbar = "1.5.0"\fR
4949
T}:T{
50-
\fBbar = "=0.22.0"\fR
50+
\fBbar = "=1.5.0"\fR
5151
T}:T{
52-
\fBbar = "0.23.0"\fR
52+
\fBbar = "2.0.0"\fR
5353
T}
5454
T{
55-
\fB0.22.0\fR
55+
\fB1.5.0\fR
5656
T}:T{
57-
Use either \fB0.22.1\fR or \fB0.22.2\fR
57+
Use either \fB1.5.1\fR or \fB1.5.2\fR
5858
T}:T{
5959
\fBReturn Error\fR
6060
T}:T{
61-
Use \fB0.23.0\fR
61+
Use \fB2.0.0\fR
6262
T}
6363
T{
64-
\fB0.22.1\fR
64+
\fB1.5.1\fR
6565
T}:T{
66-
Use either \fB0.22.0\fR or \fB0.22.2\fR
66+
Use either \fB1.5.0\fR or \fB1.5.2\fR
6767
T}:T{
68-
Use \fB0.22.0\fR
68+
Use \fB1.5.0\fR
6969
T}:T{
70-
Use \fB0.23.0\fR
70+
Use \fB2.0.0\fR
7171
T}
7272
T{
73-
\fB0.23.0\fR
73+
\fB2.0.0\fR
7474
T}:T{
75-
Use either \fB0.22.0\fR, \fB0.21.0\fR or \fB0.22.2\fR
75+
Use either \fB1.5.0\fR, \fB1.5.1\fR or \fB0.22.2\fR
7676
T}:T{
77-
Use \fB0.22.0\fR
77+
Use \fB1.5.0\fR
7878
T}:T{
7979
\fBReturn Error\fR
8080
T}

0 commit comments

Comments
 (0)