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.

Sign up for GitHub

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

Jump to bottom

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

Open
mkungla opened this issue Dec 26, 2023 · 2 comments
Open

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

mkungla opened this issue Dec 26, 2023 · 2 comments
Labels
GoCommand cmd/go modules Proposal
Milestone
Proposal

Comments

@mkungla
Copy link
Contributor

mkungla commented Dec 26, 2023

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.
@gopherbot gopherbot added this to the Proposal milestone Dec 26, 2023
@seankhliao seankhliao changed the title proposal: cmd/go: Introduce Deprecated Module Handling in go.mod for Enhanced Deprecation Management proposal: cmd/go: structures deprecated block in go.mod Dec 26, 2023
@seankhliao seankhliao changed the title proposal: cmd/go: structures deprecated block in go.mod proposal: cmd/go: structured deprecated block in go.mod Dec 26, 2023
@seankhliao
Copy link
Member

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
Copy link
Contributor Author

mkungla commented Dec 26, 2023

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 ianlancetaylor added the GoCommand cmd/go label Jan 2, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
GoCommand cmd/go modules Proposal
Projects
Proposals
Status: Incoming
Milestone
Proposal
Development

No branches or pull requests
4 participants
@ianlancetaylor @gopherbot @seankhliao @mkungla