Difference between Deprecate and retract?

Question

Today I upgraded to Go 1.17. The release notes at https://golang.org/doc/go1.17 talk about this new feature:

Module authors may deprecate a module by adding a // Deprecated: comment to go.mod

I know from Go 1.16 that go.mod file can specify a retract directive and retract a module version, or more versions.

The usage of the new // Deprecated comment is similar to retract. Please can you formally explain when I should use // Deprecate and when retract?

Astera

To over-summarize: "retract" = "do not use, now or ever"; "deprecate" = "do not use tomorrow". – Congeal

Answer 1

You should use // Deprecated: comment to indicate you don't support a major version anymore. For example you released v2.0.0, and you don't intend to work on v1.0.0 anymore. v1.0.0 may still work as intended, but it may lack many new features you only intend to add to v2.0.0.

retract can be used to mark a minor or patch version (or a range of versions enclosed in [ ]) that may contain a severe bug or vulnerability and they should not be used. For example you may release v1.2.0 and 2 days later someone discovers a security vulnerability in it. You may modify go.mod to add retract to version v1.2.0, and mark this addition as v1.2.1:

retract (
    v1.2.0 // Security vulnerability discovered.
    v1.2.1 // Contains retractions only.
    [v3.0.0, v3.9.9] // Retract all from v3
)

This will inform the go tool not to upgrade to v1.2.0 nor to v1.2.1 (e.g. when you instruct to update to the latest version with go get example.com/m@latest). When you fixed the issue and release v1.2.2, go get example.com/m@latest will update to v1.2.2.

---

Quoting from Go Modules Reference: Deprecation:

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. Individual minor and patch versions cannot be deprecated; retract may be more appropriate for that.

And quoting from retract directive:

A retract directive indicates that a version or range of versions of the module defined by go.mod should not be depended upon. A retract directive is useful when a version was published prematurely or a severe problem was discovered after the version was published. Retracted versions should remain available in version control repositories and on module proxies to ensure that builds that depend on them are not broken.

Robbert

Yes: you may both deprecate and retract all versions of a module, if you want to communicate both “prefer a different module” (deprecate) and “do not add dependencies on any existing version of this module” (retract). That said, retracting every release of a module probably suffices: “do not add dependencies on any version of this module” necessarily implies “prefer a different module”. – Goglet