go/vcs: deprecate package in favor of go list -json

This package has diverged significantly from actual cmd/go import path
resolution behavior. The recommended course of action is for people to
start using the go command itself, where this logic is guaranteed to be
up to date. cmd/go also has support for modules, while this package does
not.

I've considered two alternatives to deprecating this package:

1. Not deprecate it, keep it as is. This is not a good option because
the package deviates from cmd/go import path resolution behavior and
doesn't have all security fixes backported to it. Keeping it in this
state without deprecating it can be misleading, since people may think
this package implements the stated goal of matching cmd/go behavior and
is well supported, which is not the current reality.

2. Not deprecate it, try to make it up to date with cmd/go import path
resolution logic. This is not a good option because VCSs are no longer
guaranteed to exist for packages located inside modules. To expose the
import path to module resolution logic, the API of this package would
need to be significantly modified. At this time, my understanding is
such work is not in scope and people are encouraged to use the existing
go command instead.

In 2019, when this CL was mailed, deprecating seemed as the best option.
In 2023, when this CL was merged, deprecating seemed as the best option.

Fixes golang/go#11490.
For golang/go#57051.

Change-Id: Id32d2bec5706c4e87126b825de5215fa5d1ba8ac
Reviewed-on: https://go-review.googlesource.com/c/tools/+/159818
gopls-CI: kokoro <[email protected]>
TryBot-Result: Gopher Robot <[email protected]>
Auto-Submit: Dmitri Shuralyov <[email protected]>
Reviewed-by: Dmitri Shuralyov <[email protected]>
Reviewed-by: Bryan Mills <[email protected]>
Run-TryBot: Dmitri Shuralyov <[email protected]>

go/vcs/vcs.go

@@ -6,11 +6,17 @@
 // and using version control systems, which can be used to
 // implement behavior similar to the standard "go get" command.
 //
-// This package is a copy of internal code in package cmd/go/internal/get,
-// modified to make the identifiers exported. It's provided here
-// for developers who want to write tools with similar semantics.
-// It needs to be manually kept in sync with upstream when changes are
-// made to cmd/go/internal/get; see https://golang.org/issue/11490.
+// Deprecated: Use the go list command with -json flag instead,
+// which implements up-to-date import path resolution behavior,
+// module support, and includes the latest security fixes.
+//
+// This package was a copy of internal code in package cmd/go/internal/get
+// before module support, modified to make the identifiers exported.
+// It was provided here for developers who wanted to write tools with similar semantics.
+// It needed to be manually kept in sync with upstream when changes were
+// made to cmd/go/internal/get, as tracked in go.dev/issue/11490.
+// By now, it has diverged significantly from upstream cmd/go/internal/get
+// behavior and is not being actively updated.
 package vcs // import "golang.org/x/tools/go/vcs"
 
 import (