cmd/go: document process for tagging and deleting a package from a module

[adonovan]

On occasions when we must delete a package from a repo, we would like to provide existing clients some way to continue to use it, even though it will never be updated again. One way to achieve that is to carve out a subdirectory of the repo module as a separate module, tag it with a version, and then delete it from the repo. This way the package is available indefinitely at its latest version even though it no longer exists in the main branch of the repo. This process was used for the cmd/cover tool (see #56783) and the go/pointer package (see #59676), both within the golang.org/x/tools repo.

However, the process requires a sequence of several rather subtle CLs and the creation of many tags (each of which carries a risk of hard-to-fix mistakes). We should document the theory and practice of this approach to make it easier in future, perhaps in https://go.dev/ref/mod, or in the Go wiki.

@bcmills

[bcmills]

If someone would like to make a run at adding this documentation, the steps we have used in previous deprecations are:

1. Use go mod init to create a go.mod file in the directory to be deleted, and use go mod edit -replace to add any replace directives needed to resolve imports from other modules in the same repo. Run go mod tidy to fill in any other requirements as needed. Review and merge the commit.

   • When this commit is published, it creates a pseudo-version for the module in the parent directory which does not contain the package to be deleted.

2. Within the new module, use go mod edit -dropreplace to drop the replace directives, then go get the parent module at the commit merged in step (1). Review and merge the commit.

   • This creates a commit at which the package's requirements are consistent and self-contained (that is, they specify all needed dependencies and do not require a replace directive). In particular, this makes it so that go mod tidy and go get can add a dependency on the module without introducing ambiguous import errors (compare cmd/go: ensure that 'go mod tidy' and go get -u do not introduce ambiguous imports #27899).

3. Tag the commit merged in step (2) with a release or pre-release version, such as go/pointer/v0.1.0-deprecated. Review and push the tag.

   • This allows the go command to find the last commit containing the module even when it is no longer present at HEAD.

4. Delete the directory containing the new module. Review and merge the commit.

   • This removes the directory from the repo going forward, reducing noise in operations like git grep.

[dmitshur]

Noting here that the sequence ends up being one CL shorter when the package is standalone, since there are no local replace directives to add and later on remove. For example, see CL 505956 and its two ancestor CLs that delete x/tools/go/vcs, a package not used by the rest of x/tools.