{"id":17462857,"url":"https://github.com/mralias/erase","last_synced_at":"2025-03-28T06:41:03.613Z","repository":{"id":57704098,"uuid":"497046155","full_name":"MrAlias/erase","owner":"MrAlias","description":"Investigating how to clean out Go modules","archived":false,"fork":false,"pushed_at":"2022-06-06T21:28:10.000Z","size":49,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-02-02T07:26:17.550Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MrAlias.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-05-27T15:24:26.000Z","updated_at":"2023-07-28T01:54:55.000Z","dependencies_parsed_at":"2022-09-26T21:12:04.494Z","dependency_job_id":null,"html_url":"https://github.com/MrAlias/erase","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MrAlias%2Ferase","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MrAlias%2Ferase/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MrAlias%2Ferase/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MrAlias%2Ferase/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MrAlias","download_url":"https://codeload.github.com/MrAlias/erase/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245984561,"owners_count":20704794,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-18T09:10:06.811Z","updated_at":"2025-03-28T06:41:03.590Z","avatar_url":"https://github.com/MrAlias.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# erase\n\nWhen [a multi-module Go repository] has moved or deleted a module, without deprecation or retraction, the module becomes abandoned.\nAbandoned modules still exist in documentation and are confusing to users, especially if they are similarly named to their replacement.\n\nHow should a project handle these abandoned modules?\n\n## Goals\n\n- Code that currently compiles, continues to compile.\n- Upgrades to code that use the module inform the upgrader to use an alternate solution.\n  - Go tooling should warn the user when they try to build with the module.\n- It is clear to new users the module should not be used.\n  - Go documentation should clearly state the module should not be used, or it should not contain a listing for the module.\n- Support Go 1.17 and above.\n\n## Go module directives\n\nThe Go module system has two relevant directives: [deprecation] and [retraction]\n\n### Deprecation\n\n\u003e A module can be marked as deprecated in a block of comments containing the string `Deprecated`: (case-sensitive) at the beginning of a paragraph.\n\u003e [...]\n\u003e Deprecation messages are intended to inform users that the module is no longer supported and to provide migration instructions, for example, to the latest major version.\n\u003e Individual minor and patch versions cannot be deprecated; `retract` may be more appropriate for that.\n\n\u003e Since Go 1.17, `go list -m -u` checks for information on all deprecated modules in the build list.\n\u003e `go get` checks for deprecated modules needed to build packages named on the command line.\n\n### Retraction\n\n\u003e A retract directive indicates that a version or range of versions of the module defined by go.mod should not be depended upon.\n\u003e A retract directive is useful when a version was published prematurely or a severe problem was discovered after the version was published.\n\u003e Retracted versions should remain available in version control repositories and on module proxies to ensure that builds that depend on them are not broken.\n\n\u003e When a module version is retracted, users will not upgrade to it automatically using `go get`, `go mod tidy`, or other commands.\n\u003e Builds that depend on retracted versions should continue to work, but users will be notified of retractions when they check for updates with `go list -m -u` or update a related module with `go get`.\n\n## Investigation\n\n### Starting point\n\n![20220527_110500](https://user-images.githubusercontent.com/5543599/170767962-5506307b-6965-4c29-b98e-2b138a7e5ad0.png)\n\nOriginal respository structure:\n\n```\nerase\n├── go.mod\n├── go.sum\n├── LICENSE\n├── main.go\n├── mushroom\n│   ├── go.mod\n│   └── mushroom.go\n└── README.md\n```\n\nReleased as `v0.0.2`\n\n### Move `mushroom` -\u003e `mushrooms`\n\nNew repository structure in release `v0.0.3`:\n\n```\nerase\n├── go.mod\n├── go.sum\n├── LICENSE\n├── main.go\n├── mushrooms\n│   ├── go.mod\n│   └── mushroom.go\n└── README.md\n```\n\nNow the Go docs page lists two similar modules.\n\n![20220527_123433](https://user-images.githubusercontent.com/5543599/170778527-485be92f-825d-4807-9334-20d1072cb8bc.png)\n\nOld code that depends on `github.com/MrAlias/erase/mushroom` still compiles, but it is not obvious to new users which module to use without deeper investigation about each of their versions.\n\nThe old abandoned module, `mushroom`, needs to be cleaned up.\n\n### Deprecate `mushroom`\n\nCommunicate to the user that the `mushroom` module is no longer supported and to provide migration instructions to start using `mushrooms` by deprecating the package.\n\nUltimately this means ...\n\n- update `mushroom/go.mod` to include a deprecation notice\n- release an incremented version of `mushroom` to inclued the deprecation notice\n\nThe only issue is, the `main` branch no longer contains `mushroom/go.mod`.\nTo accomplish this a branch needs to be created from the commit prior to its removal.\n\n```sh\ngit branch erase-mushroom bfd719a~1\n```\n\nNow update `mushroom/go.mod`.\n\n```sh\nsed -i.old '1s;^;// Deprecated: use github.com/MrAlias/erase/mushrooms instead.\\n;' mushroom/go.mod\ngit commit -m \"Deprecate github.com/MrAlias/erase/mushroom\" mushroom/go.mod\ngit push origin erase-mushroom\ngit tag -s -a -m \"Release github.com/MrAlias/erase/mushroom v0.0.3\" mushroom/v0.0.3\ngit push origin mushroom/v0.0.3\n```\n\nThere is now a new `mushroom/v0.0.3` tag in the repository!\n\n![20220527_132940](https://user-images.githubusercontent.com/5543599/170785250-7d204e72-9ffb-463e-9b6b-9b9e689c43be.png)\n\nAnd similarly the package documentation lists `github.com/MrAlias/erase/mushroom` as deprecated.\n\n![20220527_133110](https://user-images.githubusercontent.com/5543599/170785481-91812348-54ba-49e5-ab19-6806323bc1c9.png)\n\nNow when packages that use `github.com/MrAlias/erase/mushroom` they are presented with the deprecation warning.\n\n```sh\n$ go get -u\ngo: module github.com/MrAlias/erase/mushroom is deprecated: use github.com/MrAlias/erase/mushrooms instead.\n```\n\nSimilarly for new additions:\n\n```sh\n$ go get github.com/MrAlias/erase/mushroom@v0.0.3\ngo: downloading github.com/MrAlias/erase v0.0.3\ngo: module github.com/MrAlias/erase/mushroom is deprecated: use github.com/MrAlias/erase/mushrooms instead.\n```\n\nThe last thing to do for this is to protect the `erase-mushroom` branch.\nIt should not be allowed to be deleted, otherwise the source of the `v0.0.3` version of module will not available.\n\nCreate an empty branch protection rule in GitHub.\n\n![20220527_135002](https://user-images.githubusercontent.com/5543599/170787801-5f05bee5-dfe9-44b9-b144-b30aa792d842.png)\n\nBy default, this protection rule will prevent the `erase-mushroom` branch from being deleted.\n\n### Remove `mushroom` from `github.com/MrAlias/erase` documentation\n\nThe `mushroom` module is deprecated, but the `github.com/MrAlias/erase` module documentation still lists it.\n\n![20220527_135806](https://user-images.githubusercontent.com/5543599/170789743-87d1012c-a3ae-46bd-bac4-659e792bdc03.png)\n\nPublishing a new version of `github.com/MrAlias/erase` does not remove it.\n\n![20220527_141722](https://user-images.githubusercontent.com/5543599/170790547-2b2ea478-d3e0-4de5-8d7e-8ca5cadb3604.png)\n\n\n\n[a multi-module Go repository]: https://github.com/open-telemetry/opentelemetry-go\n[deprecation]: https://go.dev/ref/mod#go-mod-file-module-deprecation\n[retraction]: https://golang.org/ref/mod#go-mod-file-retract\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmralias%2Ferase","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmralias%2Ferase","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmralias%2Ferase/lists"}