proposal: cmd/go: structured deprecated block in go.mod

[mkungla]

Proposal Details

Abstract

This proposal introduces a deprecated {} block within the go.mod file of Go modules. Its goal is to provide a structured, automated, and backward-compatible way for module maintainers to communicate package deprecations, including details like the last usable version, the reason for deprecation, and an optional new import path for continued development.

Rationale

The current Go module system offers deprecation notices through comments (// Deprecated: ...) and the retract {} section in go.mod. However, these approaches have limitations in terms of visibility and automation. This proposal enhances this mechanism by introducing a dedicated, structured, and easily parseable method for declaring package deprecations.

Comparison with Current Mechanism

Approach	Description	Pros	Cons
Current (// Deprecated: ..., retract {})	Manual deprecation notices in comments or go.mod.	Simple to implement.	Limited visibility and automation; lacks a standard format.
Proposed (deprecated {})	Structured block in go.mod for deprecation details.	Standardized, machine-readable format; enables automated handling of deprecated packages; detailed deprecation info and migration paths.	-

Proposed Syntax Enhancements

The deprecated {} block in go.mod could allow both detailed and shorthand declarations:

Table of Fields

Field	Required/Optional	Description
version	Required	The last usable version of the package or versions since package has been deprecated.
message	Optional	Explanation of why the package is deprecated.
newpath	Optional	New import path if package development has moved.

Shorthand Declaration Example

module github.com/example/mypackage

go 1.23

require (
    other/package v1.0.0
)

deprecated "v1.5.2" // Last usable version

Detailed Declaration Example

module github.com/example/mypackage

go 1.23

require (
    other/package v1.0.0
)

deprecated {
    version "v1.5.2"
    message "Package deprecated due to XYZ reasons. Please migrate to the new version."
    newpath "github.com/newowner/newpackage"
}

Impact on Tooling

This feature can be integrated into tools like go get and go list, providing warnings or recommendations when using deprecated packages. IDE integrations could also leverage this feature to alert developers during coding.

Addressing Potential Concerns

• Backward Compatibility: The deprecated {} block should be backward compatible, ignored by older Go versions.
• Future Extensions: This feature could pave the way for more automated deprecation handling and better integration with dependency management tools.

[seankhliao]

Note this isn't backwards compatible with older versions of Go.

version seems like redundant information, once deprecated there's generally no version that's supported, nor does it seem wise to reencode the version of the module itself in go.mod

newpath seems very restrictive, deprecation may include painting users to various other modules

tooling generally already alerts users when using deprecated modules, this does not appear to enable anything new.

see also #32816

[mkungla]

Note this isn't backwards compatible with older versions of Go.

version seems like redundant information, once deprecated there's generally no version that's supported, nor does it seem wise to reencode the version of the module itself in go.mod

newpath seems very restrictive, deprecation may include painting users to various other modules

tooling generally already alerts users when using deprecated modules, this does not appear to enable anything new.

see also #32816

I'd like to provide some clarifications regarding the points raised:

1. Version Field: The version field is intended to pinpoint the specific last working version of a package, offering a clear cut-off point for deprecation without relying on the retract field. This could be particularly useful in scenarios where only certain versions of a package are deprecated, but repo recieves new tags.

2. Backward Compatibility: While backward compatibility is indeed a concern, one possible solution could be to patch earlier versions of Go to recognize this new syntax. This approach would uphold Go's backward compatibility promise and lay a foundation for future enhancements.

3. Newpath Field: The newpath field is designed to provide an immediate redirection to a new import path, if available, following a package's deprecation. It's meant to be a straightforward, optional field that can be updated in future releases as needed.

I believe these features, with their specific purposes and flexibility, could significantly enhance the way deprecations are handled in the Go ecosystem. I'm open to further discussion and suggestions to refine these aspects of the proposal.

[ianlancetaylor]

CC @matloob

[matloob]

I agree with @seankhliao. It doesn't seem like this adds enough over the current deprecation comment format to be worth adding new syntax to go.mod files.

1. Version Field: The version field is intended to pinpoint the specific last working version of a package, offering a clear cut-off point for deprecation without relying on the retract field. This could be particularly useful in scenarios where only certain versions of a package are deprecated, but repo recieves new tags.

If versions are introduced after a deprecation happens then I think that retractions are the right way to handle them. I'm not sure why new versions of a module would be tagged after deprecation for a reason other than to add retract directives.

2. Backward Compatibility: While backward compatibility is indeed a concern, one possible solution could be to patch earlier versions of Go to recognize this new syntax. This approach would uphold Go's backward compatibility promise and lay a foundation for future enhancements.

Patching earlier versions of Go is not an option for new features like this. We support the most recently released version of go as well as the previous release but we only make minor releases for "security issues, serious problems with no workaround, and documentation fixes". (See https://go.dev/wiki/MinorReleases)

3. Newpath Field: The newpath field is designed to provide an immediate redirection to a new import path, if available, following a package's deprecation. It's meant to be a straightforward, optional field that can be updated in future releases as needed.

If the purpose is to print a message, isn't it enough to put the new module information in the deprecation message? How would the new module field be used other than to display a message?