[gopls-release-branch.0.10] gopls/internal/lsp: improve the Go version deprecation message

Improve the Go version deprecation message to be a warning at 1.13-15,
and provide better instructions for making it go away. Clarify support
in the gopls README.

Change-Id: I6b08e0bd698f5c085eee7a851a130c53affb8ab5
Reviewed-on: https://go-review.googlesource.com/c/tools/+/445581
Run-TryBot: Robert Findley <[email protected]>
Reviewed-by: Hyang-Ah Hana Kim <[email protected]>
Auto-Submit: Robert Findley <[email protected]>
Reviewed-by: Alan Donovan <[email protected]>
TryBot-Result: Gopher Robot <[email protected]>
gopls-CI: kokoro <[email protected]>
(cherry picked from commit 42cb7be)
Reviewed-on: https://go-review.googlesource.com/c/tools/+/445817

Author: findleyr

gopls/README.md

@@ -72,17 +72,22 @@ If you are having issues with `gopls`, please follow the steps described in the
 `gopls` follows the
 [Go Release Policy](https://golang.org/doc/devel/release.html#policy),
 meaning that it officially supports the last 2 major Go releases. Per
-[issue #39146](golang.org/issues/39146), we attempt to maintain best-effort
+[issue #39146](https://go.dev/issues/39146), we attempt to maintain best-effort
 support for the last 4 major Go releases, but this support extends only to not
 breaking the build and avoiding easily fixable regressions.
 
-The following table shows the final gopls version that supports being built
-with a given Go version. Go releases more recent than any in the table can
-build any version of gopls.
+In the context of this discussion, gopls "supports" a Go version if it supports
+being built with that Go version as well as integrating with the `go` command
+of that Go version.
 
-| Go Version  | Final gopls Version With Support |
-| ----------- | -------------------------------- |
+The following table shows the final gopls version that supports a given Go
+version. Go releases more recent than any in the table can be used with any
+version of gopls.
+
+| Go Version  | Final gopls version with support (without warnings) |
+| ----------- | --------------------------------------------------- |
 | Go 1.12     | [[email protected]](https://github.com/golang/tools/releases/tag/gopls%2Fv0.7.5) |
+| Go 1.15     | [[email protected]](https://github.com/golang/tools/releases/tag/gopls%2Fv0.9.5) |
 
 Our extended support is enforced via [continuous integration with older Go
 versions](doc/contributing.md#ci). This legacy Go CI may not block releases:

gopls/internal/lsp/general.go

@@ -226,11 +226,54 @@ func (s *Server) initialized(ctx context.Context, params *protocol.InitializedPa
 	return nil
 }
 
-// OldestSupportedGoVersion is the last X in Go 1.X that we support.
+// GoVersionTable maps Go versions to the gopls version in which support will
+// be deprecated, and the final gopls version supporting them without warnings.
+// Keep this in sync with gopls/README.md
 //
-// Mutable for testing, since we won't otherwise run CI on unsupported Go
-// versions.
-var OldestSupportedGoVersion = 16
+// Must be sorted in ascending order of Go version.
+//
+// Mutable for testing.
+var GoVersionTable = []GoVersionSupport{
+	{12, "", "v0.7.5"},
+	{15, "v0.11.0", "v0.9.5"},
+}
+
+// GoVersionSupport holds information about end-of-life Go version support.
+type GoVersionSupport struct {
+	GoVersion           int
+	DeprecatedVersion   string // if unset, the version is already deprecated
+	InstallGoplsVersion string
+}
+
+// OldestSupportedGoVersion is the last X in Go 1.X that this version of gopls
+// supports.
+func OldestSupportedGoVersion() int {
+	return GoVersionTable[len(GoVersionTable)-1].GoVersion + 1
+}
+
+func versionMessage(oldestVersion int) (string, protocol.MessageType) {
+	for _, v := range GoVersionTable {
+		if oldestVersion <= v.GoVersion {
+			var msgBuilder strings.Builder
+
+			mType := protocol.Error
+			fmt.Fprintf(&msgBuilder, "Found Go version 1.%d", oldestVersion)
+			if v.DeprecatedVersion != "" {
+				// not deprecated yet, just a warning
+				fmt.Fprintf(&msgBuilder, ", which will be unsupported by gopls %s. ", v.DeprecatedVersion)
+				mType = protocol.Warning
+			} else {
+				fmt.Fprint(&msgBuilder, ", which is not supported by this version of gopls. ")
+			}
+			fmt.Fprintf(&msgBuilder, "Please upgrade to Go 1.%d or later and reinstall gopls. ", OldestSupportedGoVersion())
+			fmt.Fprintf(&msgBuilder, "If you can't upgrade and want this message to go away, please install gopls %s. ", v.InstallGoplsVersion)
+			fmt.Fprint(&msgBuilder, "See https://go.dev/s/gopls-support-policy for more details.")
+
+			return msgBuilder.String(), mType
+		}
+	}
+	return "", 0
+}
 
 // checkViewGoVersions checks whether any Go version used by a view is too old,
 // raising a showMessage notification if so.
@@ -245,10 +288,9 @@ func (s *Server) checkViewGoVersions() {
 		}
 	}
 
-	if oldestVersion >= 0 && oldestVersion < OldestSupportedGoVersion {
-		msg := fmt.Sprintf("Found Go version 1.%d, which is unsupported. Please upgrade to Go 1.%d or later.", oldestVersion, OldestSupportedGoVersion)
+	if msg, mType := versionMessage(oldestVersion); msg != "" {
 		s.eventuallyShowMessage(context.Background(), &protocol.ShowMessageParams{
-			Type:    protocol.Error,
+			Type:    mType,
 			Message: msg,
 		})
 	}

gopls/internal/lsp/general_test.go

@@ -0,0 +1,43 @@
+// Copyright 2022 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package lsp
+
+import (
+	"strings"
+	"testing"
+
+	"golang.org/x/tools/gopls/internal/lsp/protocol"
+)
+
+func TestVersionMessage(t *testing.T) {
+	tests := []struct {
+		goVer        int
+		wantContains []string // string fragments that we expect to see
+		wantType     protocol.MessageType
+	}{
+		{12, []string{"1.12", "not supported", "upgrade to Go 1.16", "install gopls v0.7.5"}, protocol.Error},
+		{13, []string{"1.13", "will be unsupported by gopls v0.11.0", "upgrade to Go 1.16", "install gopls v0.9.5"}, protocol.Warning},
+		{15, []string{"1.15", "will be unsupported by gopls v0.11.0", "upgrade to Go 1.16", "install gopls v0.9.5"}, protocol.Warning},
+		{16, nil, 0},
+	}
+
+	for _, test := range tests {
+		gotMsg, gotType := versionMessage(test.goVer)
+
+		if len(test.wantContains) == 0 && gotMsg != "" {
+			t.Errorf("versionMessage(%d) = %q, want \"\"", test.goVer, gotMsg)
+		}
+
+		for _, want := range test.wantContains {
+			if !strings.Contains(gotMsg, want) {
+				t.Errorf("versionMessage(%d) = %q, want containing %q", test.goVer, gotMsg, want)
+			}
+		}
+
+		if gotType != test.wantType {
+			t.Errorf("versionMessage(%d) = returned message type %d, want %d", test.goVer, gotType, test.wantType)
+		}
+	}
+}

gopls/internal/regtest/diagnostics/diagnostics_test.go

@@ -1358,7 +1358,7 @@ func _() {
 func TestEnableAllExperiments(t *testing.T) {
 	// Before the oldest supported Go version, gopls sends a warning to upgrade
 	// Go, which fails the expectation below.
-	testenv.NeedsGo1Point(t, lsp.OldestSupportedGoVersion)
+	testenv.NeedsGo1Point(t, lsp.OldestSupportedGoVersion())
 
 	const mod = `
 -- go.mod --

gopls/internal/regtest/workspace/workspace_test.go

@@ -1242,7 +1242,7 @@ import (
 // supported.
 func TestOldGoNotification_SupportedVersion(t *testing.T) {
 	v := goVersion(t)
-	if v < lsp.OldestSupportedGoVersion {
+	if v < lsp.OldestSupportedGoVersion() {
 		t.Skipf("go version 1.%d is unsupported", v)
 	}
 
@@ -1261,7 +1261,7 @@ func TestOldGoNotification_SupportedVersion(t *testing.T) {
 // legacy Go versions (see also TestOldGoNotification_Fake)
 func TestOldGoNotification_UnsupportedVersion(t *testing.T) {
 	v := goVersion(t)
-	if v >= lsp.OldestSupportedGoVersion {
+	if v >= lsp.OldestSupportedGoVersion() {
 		t.Skipf("go version 1.%d is supported", v)
 	}
 
@@ -1285,10 +1285,12 @@ func TestOldGoNotification_Fake(t *testing.T) {
 	if err != nil {
 		t.Fatal(err)
 	}
-	defer func(v int) {
-		lsp.OldestSupportedGoVersion = v
-	}(lsp.OldestSupportedGoVersion)
-	lsp.OldestSupportedGoVersion = goversion + 1
+	defer func(t []lsp.GoVersionSupport) {
+		lsp.GoVersionTable = t
+	}(lsp.GoVersionTable)
+	lsp.GoVersionTable = []lsp.GoVersionSupport{
+		{GoVersion: goversion, InstallGoplsVersion: "v1.0.0"},
+	}
 
 	Run(t, "", func(t *testing.T, env *Env) {
 		env.Await(