_content/ref/mod.md: add more retraction examples
Borrowed from
https://seankhliao.com/blog/12021-10-17-go-mod-retract/
Updates golang/go#55834.
Change-Id: I10883a74f16caad6b62937778b09286cfd2d76d5
Reviewed-on: https://go-review.googlesource.com/c/website/+/443400
Reviewed-by: Jamal Carvalho <jamal@golang.org>
Reviewed-by: Bryan Mills <bcmills@google.com>
TryBot-Result: Gopher Robot <gobot@golang.org>
Run-TryBot: Hyang-Ah Hana Kim <hyangah@gmail.com>
diff --git a/_content/ref/mod.md b/_content/ref/mod.md
index b954697..5f5e95f 100644
--- a/_content/ref/mod.md
+++ b/_content/ref/mod.md
@@ -514,9 +514,9 @@
When the `go` command retrieves deprecation information for a module, it loads
the `go.mod` file from the version matching the `@latest` [version
-query](#version-queries) without considering retractions or exclusions. The `go`
-command loads [retractions](#glos-retracted-version) from the same `go.mod`
-file.
+query](#version-queries) without considering [retractions](#go-mod-file-retract) or
+[exclusions](#go-mod-file-exclude). The `go` command loads the list of
+[retracted versions](#glos-retracted-version) from the same `go.mod` file.
To deprecate a module, an author may add a `// Deprecated:` comment and tag a
new release. The author may change or remove the deprecation message in a higher
@@ -818,7 +818,9 @@
RetractSpec = ( Version | "[" Version "," Version "]" ) newline .
```
-Example:
+Examples:
+
+* Retracting all versions between `v1.0.0` and `v1.9.9`:
```
retract v1.0.0
@@ -829,6 +831,18 @@
)
```
+* Returning to unversioned after prematurely released a version `v1.0.0`:
+
+```
+retract [v0.0.0, v1.0.1] // assuming v1.0.1 contains this retraction.
+```
+
+* Wiping out a module including all pseudo-versions and tagged versions:
+
+```
+retract [v0.0.0-0, v0.15.2] // assuming v0.15.2 contains this retraction.
+```
+
The `retract` directive was added in Go 1.16. Go 1.15 and lower will report an
error if a `retract` directive is written in the [main
module's](#glos-main-module) `go.mod` file and will ignore `retract` directives
