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.

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.