cmd/go: deprecate a major module version

[peterbourgon]

Proposal: A Mechanism For Deprecating Modules

Authors: @peterbourgon, @adg

This proposal is a replacement for part of #38762. The other part is replaced by #40323.

Problem

Currently, there is no standard way for package authors to signal to consumers that a major version of a package is deprecated and no longer supported. Package consumers can easily inadvertently select an unmaintained major version (see #40323) and miss important new features or bug fixes.

Proposal

We propose adding a Deprecated: comment for modules that is recognized by go tooling to flag that a module version as deprecated. This is parallel to the Deprecated: comments that can be used to flag a package or identifier as deprecated.

When selecting a deprecated module version, the go tool will print a note to the user alerting them to the deprecation, and printing the deprecation text provided by the module author. Authors can use this notification to direct package consumers to more recent major versions, or an entirely new module that replaces the deprecated one.

As with package-level deprecation comments, module deprecation comments can span multiple lines.

Example

The author of module github.com/peterbourgon/ff has released a new major version v2 (current version v2.0.1), and wants to deprecate the old major version tree v1 (latest version v1.7.4).

In the v1 branch, they add a module declaration to the go.mod file, above the module declaration:

// Deprecated: The latest supported version is github.com/peterbourgon/ff/v2.
module github.com/peterbourgon/ff

They commit this change and tag it as a new patch release v1.7.5.

There are several ways this deprecation message will or will not be displayed to package consumers.

If a consumer is fetching the module at major version v1 for the first time, the command succeeds but a deprecation warning is printed as part of go get's output:

$ go get gthub.com/peterbourgon/ff
go: deprecated: github.com/peterbourgon/ff v1.7.5 👈
go: deprecated: The latest supported version is github.com/peterbourgon/ff/v2. 👈

If a consumer is currently using the module at version e.g. v1.7.4, no warnings will be printed when that module version is fetched. However, if the consumer tries to upgrade the dependency, they will see the deprecation warning. Notably, the upgrade will still succeed.

$ go get -u github.com/peterbourgon/ff
go: github.com/peterbourgon/ff upgrade => v1.7.5
go: deprecated: github.com/peterbourgon/ff v1.7.5 👈
go: deprecated: The latest supported version is github.com/peterbourgon/ff/v2. 👈

If a consumer is currently using the module at major version 1 (e.g. v1.7.4), and runs a command that lists the latest version available in that major version tree (i.e. v1.7.5), the warning is printed.

$ go list -m -u all
example.com/my-module
github.com/BurntSushi/toml v0.3.1
github.com/mitchellh/go-wordwrap v1.0.0
github.com/peterbourgon/ff v1.7.4 [v1.7.5]
go: deprecated: github.com/peterbourgon/ff v1.7.5 👈
go: deprecated: The latest supported version is github.com/peterbourgon/ff/v2. 👈

Integrations

pkg.go.dev

Module deprecation warnings should be prominently displayed on pkg.go.dev. It is worth exploring the linkification of module paths when displaying module deprecation notices.

Editor integration

If and when editors upgrade dependencies, these deprecation notices should be surfaced to the user as appropriate.

[cespare]

If both #40323 and this proposal were accepted:

• Am I correct that you propose alerts under the same set of operations?
• If a module version were deprecated and there's a newer major module version available, do you propose to print both warnings?

[peterbourgon]

Am I correct that you propose alerts under the same set of operations?

To the best of my knowledge, yes: when a module consumer first adds a version of a module to their project which meets the respective criteria.

If a module version were deprecated and there's a newer major module version available, do you propose to print both warnings?

Yes.

[bcmills]

To me, this has the same issue as proposal #40323: a one-time warning when the dependency is added is easy to miss.

Module deprecation seems like a good thing to surface in gorelease, gopls, and pkg.go.dev. go get and go mod tidy seem far too late in the development cycle, and too ephemeral anyway.

CC @jayconrod @matloob

[peterbourgon]

To me, this has the same issue as proposal #40323: a one-time warning when the dependency is added is easy to miss . . . go get and go mod tidy seem far too late in the development cycle, and too ephemeral anyway.

I don't really understand these points. When I add a new module dependency to my project, and then run whichever go command will cause it to be fetched — either directly in the terminal, or indirectly through my editor integration — I always watch to see the results of the fetch. Don't you? And isn't that moment, when your project first gains knowledge of a new dependency, precisely the moment when you'd want to be alerted to information like this?

Maybe we have different workflows, that's possible. I'd love to understand yours.

[bcmills]

When I add a new module dependency to my project, and then run whichever go command will cause it to be fetched — either directly in the terminal, or indirectly through my editor integration — I always watch to see the results of the fetch. Don't you?

If I make a change to a file and then run go test on the package containing that file, I generally watch for the results of the test — not for other changes to module versions that happened to precede the actual test run. (To examine the resulting changes to module requirements, I use git diff after the code is actually working.)

[peterbourgon]

If I make a change to a file

We're not talking about just making a change, we're talking about the first time you add a new dependency to a project, which is much less routine.

I generally watch for the results of the test — not for other changes to module versions that happened to precede the actual test run.

OK, I think it's clear that the changes in this proposal are likely to be missed by your workflow. I'm not convinced that (a) your workflow is typical, or (b) that in any case this should impact the proposal.

[rogpeppe]

OK, I think it's clear that the changes in this proposal are likely to be missed by your workflow. I'm not convinced that (a) your workflow is typical, or (b) that in any case this should impact the proposal.

FWIW my workflow is similar. When making changes to a project that might be using new dependencies, the test and/or build output can be verbose and I fear that these warnings would be lost in the noise. The warnings wouldn't be repeated AIUI, so I'm not convinced that this feature is as useful as it could be.

As usual, warnings are often ignored. I think I'd prefer to have a feature that made it an error to add a new direct dependency that's deprecated (either opt-in, or as default behaviour with a way to opt out of it).

[myitcv]

I always watch to see the results of the fetch. Don't you?

@peterbourgon can you provide more detail on your workflow?

I ask because from my perspective and experience of using gopls, the majority of people will end up adding requirements to their go.mod indirectly via gopls (largely via the goimports-esque workflow). My gut feeling is that the majority of people (based on the assumption that the majority of Go developers today use gopls) will not use go get directly when it comes to adding/upgrading a dependency.

That's not to say we shouldn't support a notification when invoking go get. However I share @bcmills' and @rogpeppe's concerns that this would, in most cases, be a notification that is missed by virtue of it getting buried in other output or because cmd/go isn't the end tool being used.

Module deprecation seems like a good thing to surface in gorelease, gopls, and pkg.go.dev. go get and go mod tidy seem far too late in the development cycle, and too ephemeral anyway.

Agreed. That said, getting UX for gopls "right" so as not to be annoying will be tricky (although we should do something).

cc @stamblerre for gopls

[zikaeroh]

I ask because from my perspective and experience of using gopls, the majority of people will end up adding requirements to their go.mod indirectly via gopls (largely via the goimports-esque workflow). My gut feeling is that the majority of people (based on the assumption that the majority of Go developers today use gopls) will not use go get directly when it comes to adding/upgrading a dependency.

I was quite literally just typing this out! 🙂

My workflow when it comes to new libs is to copy out of pkg.go.dev or my browser's URL bar directly into my editor, and then gopls will eventually make a change to my go.mod file by virtue that the tooling manages updates it. Then, I'll go back in the terminal some time later to go mod tidy and clean things up. I'm much less often at the terminal running go get unless I'm there to explicitly upgrade something or am doing something where I need go mod edit or gohack or something.

I'll also bring up that I think some users (at least with gopls in VS Code) may be running tests in the editor, be it by running the handy "run tests with coverage" commands or a code lens to run a specific test, in which case they may never see go test's output unless it fails. (I don't fall into this category, except when looking for coverage or debugging a test; I usually run tests in a separate terminal.)

[peterbourgon]

@peterbourgon can you provide more detail on your workflow?

I ask because from my perspective and experience of using gopls, the majority of people will end up adding requirements to their go.mod indirectly via gopls (largely via the goimports-esque workflow). My gut feeling is that the majority of people (based on the assumption that the majority of Go developers today use gopls) will not use go get directly when it comes to adding/upgrading a dependency.

Most of the time my workflow is like this, too. I'd say about 30% of the time I manually go get a new module in the terminal. In neither case do I ignore or only partially read the output of the next go tool command which ends up actually performing the version resolution and the fetch.

To the broader point, editor integration is important, and I would indeed hope/expect the warning message to be parsed and surfaced in a more visible way in the editor by gopls. I'm not sure if that's a little warning dialog, like when you need to recompile your tools; or a prominent message postfixed to the output pane; or what, exactly. But it seemed like an over-reach for the proposals to dictate how that should work. Once the message is in the output, tooling can surface it however makes sense.

[peterbourgon]

To zoom out a bit, I think we'd be happy to amend the proposal(s) to describe additional places or ways to emit the warning. The mechanisms listed were simply the most obvious to us at time.

We agree that editor integration and pkg.go.dev are important. I'm not sure about gorelease — presumably you meant goreleaser — because I want to be notified before I start writing code, not after. But maybe I'm not understanding the idea there.