gopls: warn against using go get -tool with gopls

The problem is that gopls needs exactly the right version
of x/tools, as found on its release branch. The solution
to an MVS constraint system which requires x/tools at
higher versions will inevitably lead to build failures.

(We should move modernize to x/tools.)

Updates golang/go#73279

Change-Id: I6f43bb2e74b29384cedcb92b5d958cf695aa529d
Reviewed-on: https://go-review.googlesource.com/c/tools/+/665636
Reviewed-by: Robert Findley <[email protected]>
Auto-Submit: Alan Donovan <[email protected]>
LUCI-TryBot-Result: Go LUCI <[email protected]>

Author: adonovan

gopls/doc/analyzers.md

@@ -492,6 +492,8 @@ following command:
 
 	$ go run golang.org/x/tools/gopls/internal/analysis/modernize/cmd/modernize@latest -fix -test ./...
 
+(Do not use "go get -tool" to add gopls as a dependency of your module; it will not work.)
+
 If the tool warns of conflicting fixes, you may need to run it more
 than once until it has applied all fixes cleanly. This command is
 not an officially supported interface and may change in the future.

gopls/internal/analysis/modernize/doc.go

@@ -25,6 +25,8 @@
 //
 //	$ go run golang.org/x/tools/gopls/internal/analysis/modernize/cmd/modernize@latest -fix -test ./...
 //
+// (Do not use "go get -tool" to add gopls as a dependency of your module; it will not work.)
+//
 // If the tool warns of conflicting fixes, you may need to run it more
 // than once until it has applied all fixes cleanly. This command is
 // not an officially supported interface and may change in the future.

gopls/internal/doc/api.json

@@ -562,7 +562,7 @@
 						},
 						{
 							"Name": "\"modernize\"",
-							"Doc": "simplify code by using modern constructs\n\nThis analyzer reports opportunities for simplifying and clarifying\nexisting code by using more modern features of Go and its standard\nlibrary.\n\nEach diagnostic provides a fix. Our intent is that these fixes may\nbe safely applied en masse without changing the behavior of your\nprogram. In some cases the suggested fixes are imperfect and may\nlead to (for example) unused imports or unused local variables,\ncausing build breakage. However, these problems are generally\ntrivial to fix. We regard any modernizer whose fix changes program\nbehavior to have a serious bug and will endeavor to fix it.\n\nTo apply all modernization fixes en masse, you can use the\nfollowing command:\n\n\t$ go run golang.org/x/tools/gopls/internal/analysis/modernize/cmd/modernize@latest -fix -test ./...\n\nIf the tool warns of conflicting fixes, you may need to run it more\nthan once until it has applied all fixes cleanly. This command is\nnot an officially supported interface and may change in the future.\n\nChanges produced by this tool should be reviewed as usual before\nbeing merged. In some cases, a loop may be replaced by a simple\nfunction call, causing comments within the loop to be discarded.\nHuman judgment may be required to avoid losing comments of value.\n\nEach diagnostic reported by modernize has a specific category. (The\ncategories are listed below.) Diagnostics in some categories, such\nas \"efaceany\" (which replaces \"interface{}\" with \"any\" where it is\nsafe to do so) are particularly numerous. It may ease the burden of\ncode review to apply fixes in two passes, the first change\nconsisting only of fixes of category \"efaceany\", the second\nconsisting of all others. This can be achieved using the -category flag:\n\n\t$ modernize -category=efaceany  -fix -test ./...\n\t$ modernize -category=-efaceany -fix -test ./...\n\nCategories of modernize diagnostic:\n\n  - forvar: remove x := x variable declarations made unnecessary by the new semantics of loops in go1.22.\n\n  - slicescontains: replace 'for i, elem := range s { if elem == needle { ...; break }'\n    by a call to slices.Contains, added in go1.21.\n\n  - minmax: replace an if/else conditional assignment by a call to\n    the built-in min or max functions added in go1.21.\n\n  - sortslice: replace sort.Slice(x, func(i, j int) bool) { return s[i] \u003c s[j] }\n    by a call to slices.Sort(s), added in go1.21.\n\n  - efaceany: replace interface{} by the 'any' type added in go1.18.\n\n  - slicesclone: replace append([]T(nil), s...) by slices.Clone(s) or\n    slices.Concat(s), added in go1.21.\n\n  - mapsloop: replace a loop around an m[k]=v map update by a call\n    to one of the Collect, Copy, Clone, or Insert functions from\n    the maps package, added in go1.21.\n\n  - fmtappendf: replace []byte(fmt.Sprintf...) by fmt.Appendf(nil, ...),\n    added in go1.19.\n\n  - testingcontext: replace uses of context.WithCancel in tests\n    with t.Context, added in go1.24.\n\n  - omitzero: replace omitempty by omitzero on structs, added in go1.24.\n\n  - bloop: replace \"for i := range b.N\" or \"for range b.N\" in a\n    benchmark with \"for b.Loop()\", and remove any preceding calls\n    to b.StopTimer, b.StartTimer, and b.ResetTimer.\n\n  - slicesdelete: replace append(s[:i], s[i+1]...) by\n    slices.Delete(s, i, i+1), added in go1.21.\n\n  - rangeint: replace a 3-clause \"for i := 0; i \u003c n; i++\" loop by\n    \"for i := range n\", added in go1.22.\n\n  - stringsseq: replace Split in \"for range strings.Split(...)\" by go1.24's\n    more efficient SplitSeq, or Fields with FieldSeq.\n\n  - stringscutprefix: replace some uses of HasPrefix followed by TrimPrefix with CutPrefix,\n    added to the strings package in go1.20.\n\n  - waitgroup: replace old complex usages of sync.WaitGroup by less complex WaitGroup.Go method in go1.25.",
+							"Doc": "simplify code by using modern constructs\n\nThis analyzer reports opportunities for simplifying and clarifying\nexisting code by using more modern features of Go and its standard\nlibrary.\n\nEach diagnostic provides a fix. Our intent is that these fixes may\nbe safely applied en masse without changing the behavior of your\nprogram. In some cases the suggested fixes are imperfect and may\nlead to (for example) unused imports or unused local variables,\ncausing build breakage. However, these problems are generally\ntrivial to fix. We regard any modernizer whose fix changes program\nbehavior to have a serious bug and will endeavor to fix it.\n\nTo apply all modernization fixes en masse, you can use the\nfollowing command:\n\n\t$ go run golang.org/x/tools/gopls/internal/analysis/modernize/cmd/modernize@latest -fix -test ./...\n\n(Do not use \"go get -tool\" to add gopls as a dependency of your module; it will not work.)\n\nIf the tool warns of conflicting fixes, you may need to run it more\nthan once until it has applied all fixes cleanly. This command is\nnot an officially supported interface and may change in the future.\n\nChanges produced by this tool should be reviewed as usual before\nbeing merged. In some cases, a loop may be replaced by a simple\nfunction call, causing comments within the loop to be discarded.\nHuman judgment may be required to avoid losing comments of value.\n\nEach diagnostic reported by modernize has a specific category. (The\ncategories are listed below.) Diagnostics in some categories, such\nas \"efaceany\" (which replaces \"interface{}\" with \"any\" where it is\nsafe to do so) are particularly numerous. It may ease the burden of\ncode review to apply fixes in two passes, the first change\nconsisting only of fixes of category \"efaceany\", the second\nconsisting of all others. This can be achieved using the -category flag:\n\n\t$ modernize -category=efaceany  -fix -test ./...\n\t$ modernize -category=-efaceany -fix -test ./...\n\nCategories of modernize diagnostic:\n\n  - forvar: remove x := x variable declarations made unnecessary by the new semantics of loops in go1.22.\n\n  - slicescontains: replace 'for i, elem := range s { if elem == needle { ...; break }'\n    by a call to slices.Contains, added in go1.21.\n\n  - minmax: replace an if/else conditional assignment by a call to\n    the built-in min or max functions added in go1.21.\n\n  - sortslice: replace sort.Slice(x, func(i, j int) bool) { return s[i] \u003c s[j] }\n    by a call to slices.Sort(s), added in go1.21.\n\n  - efaceany: replace interface{} by the 'any' type added in go1.18.\n\n  - slicesclone: replace append([]T(nil), s...) by slices.Clone(s) or\n    slices.Concat(s), added in go1.21.\n\n  - mapsloop: replace a loop around an m[k]=v map update by a call\n    to one of the Collect, Copy, Clone, or Insert functions from\n    the maps package, added in go1.21.\n\n  - fmtappendf: replace []byte(fmt.Sprintf...) by fmt.Appendf(nil, ...),\n    added in go1.19.\n\n  - testingcontext: replace uses of context.WithCancel in tests\n    with t.Context, added in go1.24.\n\n  - omitzero: replace omitempty by omitzero on structs, added in go1.24.\n\n  - bloop: replace \"for i := range b.N\" or \"for range b.N\" in a\n    benchmark with \"for b.Loop()\", and remove any preceding calls\n    to b.StopTimer, b.StartTimer, and b.ResetTimer.\n\n  - slicesdelete: replace append(s[:i], s[i+1]...) by\n    slices.Delete(s, i, i+1), added in go1.21.\n\n  - rangeint: replace a 3-clause \"for i := 0; i \u003c n; i++\" loop by\n    \"for i := range n\", added in go1.22.\n\n  - stringsseq: replace Split in \"for range strings.Split(...)\" by go1.24's\n    more efficient SplitSeq, or Fields with FieldSeq.\n\n  - stringscutprefix: replace some uses of HasPrefix followed by TrimPrefix with CutPrefix,\n    added to the strings package in go1.20.\n\n  - waitgroup: replace old complex usages of sync.WaitGroup by less complex WaitGroup.Go method in go1.25.",
 							"Default": "true",
 							"Status": ""
 						},
@@ -1338,7 +1338,7 @@
 		},
 		{
 			"Name": "modernize",
-			"Doc": "simplify code by using modern constructs\n\nThis analyzer reports opportunities for simplifying and clarifying\nexisting code by using more modern features of Go and its standard\nlibrary.\n\nEach diagnostic provides a fix. Our intent is that these fixes may\nbe safely applied en masse without changing the behavior of your\nprogram. In some cases the suggested fixes are imperfect and may\nlead to (for example) unused imports or unused local variables,\ncausing build breakage. However, these problems are generally\ntrivial to fix. We regard any modernizer whose fix changes program\nbehavior to have a serious bug and will endeavor to fix it.\n\nTo apply all modernization fixes en masse, you can use the\nfollowing command:\n\n\t$ go run golang.org/x/tools/gopls/internal/analysis/modernize/cmd/modernize@latest -fix -test ./...\n\nIf the tool warns of conflicting fixes, you may need to run it more\nthan once until it has applied all fixes cleanly. This command is\nnot an officially supported interface and may change in the future.\n\nChanges produced by this tool should be reviewed as usual before\nbeing merged. In some cases, a loop may be replaced by a simple\nfunction call, causing comments within the loop to be discarded.\nHuman judgment may be required to avoid losing comments of value.\n\nEach diagnostic reported by modernize has a specific category. (The\ncategories are listed below.) Diagnostics in some categories, such\nas \"efaceany\" (which replaces \"interface{}\" with \"any\" where it is\nsafe to do so) are particularly numerous. It may ease the burden of\ncode review to apply fixes in two passes, the first change\nconsisting only of fixes of category \"efaceany\", the second\nconsisting of all others. This can be achieved using the -category flag:\n\n\t$ modernize -category=efaceany  -fix -test ./...\n\t$ modernize -category=-efaceany -fix -test ./...\n\nCategories of modernize diagnostic:\n\n  - forvar: remove x := x variable declarations made unnecessary by the new semantics of loops in go1.22.\n\n  - slicescontains: replace 'for i, elem := range s { if elem == needle { ...; break }'\n    by a call to slices.Contains, added in go1.21.\n\n  - minmax: replace an if/else conditional assignment by a call to\n    the built-in min or max functions added in go1.21.\n\n  - sortslice: replace sort.Slice(x, func(i, j int) bool) { return s[i] \u003c s[j] }\n    by a call to slices.Sort(s), added in go1.21.\n\n  - efaceany: replace interface{} by the 'any' type added in go1.18.\n\n  - slicesclone: replace append([]T(nil), s...) by slices.Clone(s) or\n    slices.Concat(s), added in go1.21.\n\n  - mapsloop: replace a loop around an m[k]=v map update by a call\n    to one of the Collect, Copy, Clone, or Insert functions from\n    the maps package, added in go1.21.\n\n  - fmtappendf: replace []byte(fmt.Sprintf...) by fmt.Appendf(nil, ...),\n    added in go1.19.\n\n  - testingcontext: replace uses of context.WithCancel in tests\n    with t.Context, added in go1.24.\n\n  - omitzero: replace omitempty by omitzero on structs, added in go1.24.\n\n  - bloop: replace \"for i := range b.N\" or \"for range b.N\" in a\n    benchmark with \"for b.Loop()\", and remove any preceding calls\n    to b.StopTimer, b.StartTimer, and b.ResetTimer.\n\n  - slicesdelete: replace append(s[:i], s[i+1]...) by\n    slices.Delete(s, i, i+1), added in go1.21.\n\n  - rangeint: replace a 3-clause \"for i := 0; i \u003c n; i++\" loop by\n    \"for i := range n\", added in go1.22.\n\n  - stringsseq: replace Split in \"for range strings.Split(...)\" by go1.24's\n    more efficient SplitSeq, or Fields with FieldSeq.\n\n  - stringscutprefix: replace some uses of HasPrefix followed by TrimPrefix with CutPrefix,\n    added to the strings package in go1.20.\n\n  - waitgroup: replace old complex usages of sync.WaitGroup by less complex WaitGroup.Go method in go1.25.",
+			"Doc": "simplify code by using modern constructs\n\nThis analyzer reports opportunities for simplifying and clarifying\nexisting code by using more modern features of Go and its standard\nlibrary.\n\nEach diagnostic provides a fix. Our intent is that these fixes may\nbe safely applied en masse without changing the behavior of your\nprogram. In some cases the suggested fixes are imperfect and may\nlead to (for example) unused imports or unused local variables,\ncausing build breakage. However, these problems are generally\ntrivial to fix. We regard any modernizer whose fix changes program\nbehavior to have a serious bug and will endeavor to fix it.\n\nTo apply all modernization fixes en masse, you can use the\nfollowing command:\n\n\t$ go run golang.org/x/tools/gopls/internal/analysis/modernize/cmd/modernize@latest -fix -test ./...\n\n(Do not use \"go get -tool\" to add gopls as a dependency of your module; it will not work.)\n\nIf the tool warns of conflicting fixes, you may need to run it more\nthan once until it has applied all fixes cleanly. This command is\nnot an officially supported interface and may change in the future.\n\nChanges produced by this tool should be reviewed as usual before\nbeing merged. In some cases, a loop may be replaced by a simple\nfunction call, causing comments within the loop to be discarded.\nHuman judgment may be required to avoid losing comments of value.\n\nEach diagnostic reported by modernize has a specific category. (The\ncategories are listed below.) Diagnostics in some categories, such\nas \"efaceany\" (which replaces \"interface{}\" with \"any\" where it is\nsafe to do so) are particularly numerous. It may ease the burden of\ncode review to apply fixes in two passes, the first change\nconsisting only of fixes of category \"efaceany\", the second\nconsisting of all others. This can be achieved using the -category flag:\n\n\t$ modernize -category=efaceany  -fix -test ./...\n\t$ modernize -category=-efaceany -fix -test ./...\n\nCategories of modernize diagnostic:\n\n  - forvar: remove x := x variable declarations made unnecessary by the new semantics of loops in go1.22.\n\n  - slicescontains: replace 'for i, elem := range s { if elem == needle { ...; break }'\n    by a call to slices.Contains, added in go1.21.\n\n  - minmax: replace an if/else conditional assignment by a call to\n    the built-in min or max functions added in go1.21.\n\n  - sortslice: replace sort.Slice(x, func(i, j int) bool) { return s[i] \u003c s[j] }\n    by a call to slices.Sort(s), added in go1.21.\n\n  - efaceany: replace interface{} by the 'any' type added in go1.18.\n\n  - slicesclone: replace append([]T(nil), s...) by slices.Clone(s) or\n    slices.Concat(s), added in go1.21.\n\n  - mapsloop: replace a loop around an m[k]=v map update by a call\n    to one of the Collect, Copy, Clone, or Insert functions from\n    the maps package, added in go1.21.\n\n  - fmtappendf: replace []byte(fmt.Sprintf...) by fmt.Appendf(nil, ...),\n    added in go1.19.\n\n  - testingcontext: replace uses of context.WithCancel in tests\n    with t.Context, added in go1.24.\n\n  - omitzero: replace omitempty by omitzero on structs, added in go1.24.\n\n  - bloop: replace \"for i := range b.N\" or \"for range b.N\" in a\n    benchmark with \"for b.Loop()\", and remove any preceding calls\n    to b.StopTimer, b.StartTimer, and b.ResetTimer.\n\n  - slicesdelete: replace append(s[:i], s[i+1]...) by\n    slices.Delete(s, i, i+1), added in go1.21.\n\n  - rangeint: replace a 3-clause \"for i := 0; i \u003c n; i++\" loop by\n    \"for i := range n\", added in go1.22.\n\n  - stringsseq: replace Split in \"for range strings.Split(...)\" by go1.24's\n    more efficient SplitSeq, or Fields with FieldSeq.\n\n  - stringscutprefix: replace some uses of HasPrefix followed by TrimPrefix with CutPrefix,\n    added to the strings package in go1.20.\n\n  - waitgroup: replace old complex usages of sync.WaitGroup by less complex WaitGroup.Go method in go1.25.",
 			"URL": "https://pkg.go.dev/golang.org/x/tools/gopls/internal/analysis/modernize",
 			"Default": true
 		},

internal/gofix/doc.go

@@ -83,6 +83,8 @@ You can use this (officially unsupported) command to apply gofix fixes en masse:
 
 	$ go run golang.org/x/tools/gopls/internal/analysis/gofix/cmd/gofix@latest -test ./...
 
+(Do not use "go get -tool" to add gopls as a dependency of your module; it will not work.)
+
 # Analyzer gofixdirective
 
 gofixdirective: validate uses of gofix comment directives