Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

adonovan opened this issue Jun 1, 2023 · 2 comments
Documentation modules NeedsFix The path to resolution is known, but the work has not been done.


Copy link

adonovan commented Jun 1, 2023

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 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, or in the Go wiki.


@mknyszek mknyszek added the NeedsFix The path to resolution is known, but the work has not been done. label Jun 1, 2023
@mknyszek mknyszek added this to the Backlog milestone Jun 1, 2023
@bcmills bcmills added the modules label Jun 1, 2023
Copy link

bcmills commented Jun 20, 2023

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.

  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.

Copy link

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Documentation modules NeedsFix The path to resolution is known, but the work has not been done.
None yet

No branches or pull requests

5 participants