Modules: clarify 1.22+ conversions from gopkg.lock
Fixes golang/go#72916
Change-Id: Icec2f79d83a1a2d09490a731297e9c97802b3dc9
GitHub-Last-Rev: 8de3163429b7451464be24e20a2dca4cc5015748
GitHub-Pull-Request: golang/wiki#47
Reviewed-on: https://go-review.googlesource.com/c/wiki/+/658735
Reviewed-by: Sean Liao <sean@liao.dev>
Auto-Submit: Sean Liao <sean@liao.dev>
diff --git a/Modules.md b/Modules.md
index 503d81f..d11e4bd 100644
--- a/Modules.md
+++ b/Modules.md
@@ -347,7 +347,6 @@
```
$ go mod init
```
- This step converts from any existing [`dep`](https://github.com/golang/dep) `Gopkg.lock` file or any of the other [nine total supported dependency formats](https://tip.golang.org/pkg/cmd/go/internal/modconv/?m=all#pkg-variables), adding require statements to match the existing configuration.
`go mod init` will often be able to use auxiliary data (such as VCS meta-data) to automatically determine the appropriate module path, but if `go mod init` states it can not automatically determine the module path, or if you need to otherwise override that path, you can supply the [module path](/wiki/Modules#gomod) as an optional argument to `go mod init`, for example:
@@ -357,6 +356,8 @@
Note that if your dependencies include v2+ modules, or if you are initializing a v2+ module, then after running `go mod init` you might also need to edit your `go.mod` and `.go` code to add `/vN` to import paths and module paths as described in the ["Semantic Import Versioning"](/wiki/Modules#semantic-import-versioning) section above. This applies even if `go mod init` automatically converted your dependency information from `dep` or other dependency managers. (Because of this, after running `go mod init`, you typically should not run `go mod tidy` until you have successfully run `go build ./...` or similar, which is the sequence shown in this section).
+ If used with go 1.21.13 or older, this step also converts from any existing [`dep`](https://github.com/golang/dep) `Gopkg.lock` file or any of the other [nine total supported dependency formats](https://pkg.go.dev/cmd/go/internal/modconv@go1.21.13#pkg-variables), adding require statements to match the existing configuration.
+
3. Build the module. When executed from the root directory of a module, the `./...` pattern matches all the packages within the current module. `go build` will automatically add missing or unconverted dependencies as needed to satisfy imports for this particular build invocation:
```
@@ -497,7 +498,7 @@
#### Automatic Migration from Prior Dependency Managers
- * `go mod init` automatically translates the required information from [dep, glide, govendor, godep, and 5 other pre-existing dependency managers](https://tip.golang.org/pkg/cmd/go/internal/modconv/?m=all#pkg-variables) into a `go.mod `file that produces the equivalent build.
+ * With go 1.21.13 or older, `go mod init` automatically translates the required information from [dep, glide, govendor, godep, and 5 other pre-existing dependency managers](https://pkg.go.dev/cmd/go/internal/modconv@go1.21.13#pkg-variables) into a `go.mod `file that produces the equivalent build.
* If you are creating a v2+ module, be sure your `module` directive in the converted `go.mod` includes the appropriate `/vN` (e.g., `module foo/v3`).
* Note that if you are importing v2+ modules, you might need to do some manual adjustments after an initial conversion in order to add `/vN` to the `require` statements that `go mod init` generates after translating from a prior dependency manager. See the ["How to Define a Module"](/wiki/Modules#how-to-define-a-module) section above for more details.
* In addition, `go mod init` will not edit your `.go` code to add any required `/vN` to import statements. See the ["Semantic Import versioning"](/wiki/Modules#semantic-import-versioning) and ["Releasing Modules (v2 or Higher)"](/wiki/Modules#releasing-modules-v2-or-higher) sections above for the required steps, including some options around community tools to automate the conversion.
@@ -1320,6 +1321,8 @@
Yes. This requires some manual steps, but can be helpful in some more complex cases.
+Go versions 1.21 and older attempted to convert a prior dependency manager formats to `go.mod` formats. The following instructions thus need 1.21.13 or older; you need to run the following with `GOTOOLCHAIN=go1.21.13`, or install an older version of go manually.
+
When you run `go mod init` when initializing your own module, it will automatically convert from a prior dependency manager by translating configuration files like `Gopkg.lock`, `glide.lock`, or `vendor.json` into a `go.mod` file that contains corresponding `require` directives. The information in a pre-existing `Gopkg.lock` file for example usually describes version information for all of your direct and indirect dependencies.
However, if instead you are adding a new dependency that has not yet opted in to modules itself, there is not a similar automatic conversion process from any prior dependency manager that your new dependency might have been using. If that new dependency itself has non-module dependencies that have had breaking changes, then in some cases that can cause incompatibility problems. In other words, a prior dependency manager of your new dependency is not automatically used, and that can cause problems with your indirect dependencies in some cases.
