proposal: cmd/go: notify about newer major versions

[zachgersh]

Proposal: Major Module Version Alerts

This is a unification of two separate proposals (#38762 and #38502) that seek to alert users to the fact that a set of new major module versions may be available for inclusion in their project.

Problem

Semantic Import Versioning introduced the concept of a version suffix, which needs to be explicitly specified on your module path for major versions greater than 1. It is easy for users to consume a v0/v1 version of a module by default, even if they would be better served by selecting the most recent major version.

Discoverability is a key issue. The mechanisms for module authors to advertise recent major versions are inconsistent, and can be low-visibility (documentation? README.md?) or highly disruptive (printing deprecation warnings in init, broken builds to force an investigation).

Abstract

We propose a mechanism that notifies users of the latest major version of a module dependency when (a) that dependency is first added to the project; (b) they update to a newer minor or patch version; or (c) they list out dependencies that can be upgraded.

The proposed notification is informational; the user will have to decide the best course of action (stay with the v0/v1 version they fetched, or update their code to use a later version). We understand that automatic upgrades are not generally possible, as new major semantic versions are necessarily incompatible with previous ones.

Proposal

We propose notifying users of new major versions when:

• They first add a requirement for an old major version of a module
• They update a requirement for an old major version of a module
• They list dependencies that can be updated

There are a few ways users add requirements to their modules:

• By running go get github.com/user/repo
• By adding a require github.com/user/repo line to their go.mod file manually
• By adding an import line to a Go source file, and having goimports or gopls editor integration add the import line on save

For the latter two, the module isn't fetched until the go command is invoked within the module.

There are a few ways users update requirements:

• By running go get [-u] github.com/user/repo
• By running go get -u ./... from the module root

And there is one way users find out about available updates:

• By running go list -m -u all

We propose to, in these cases, have the go tool print a note when a more recent major version of the module is available.

Examples

Consider a user fetching github.com/peterbourgon/ff with go get. We propose adding a notification to the output, alerting the user to a new major version:

$ go get github.com/peterbourgon/ff
go: finding github.com/pelletier/go-toml v1.6.0
go: finding gopkg.in/yaml.v2 v2.2.4
go: finding github.com/davecgh/go-spew v1.1.1
go: downloading github.com/peterbourgon/ff v1.7.0
go: extracting github.com/peterbourgon/ff v1.7.0
go: note: a more recent major version is available: github.com/peterbourgon/ff/v3 [v3.1.0]  👈

Consider a user listing all of the most recent versions of their dependencies. We propose printing the same note to standard error after any new minor or patch versions:

$ 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.6.0 [v1.7.0]
go: note: a more recent major version is available: github.com/peterbourgon/ff/v3 [v3.1.0] 👈

If the requirement is added to the go.mod file manually, the go tool would print the notification when it first fetches the new module, as part of a go build, go test, etc. run.

Integrations

pkg.go.dev

The Go package discovery website at pkg.go.dev shows modules and their versions. However, it obscures successive major versions when they exist, apparently treating major module versions as completely distinct. For example, the landing page for peterbourgon/ff shows v1.7.0 with a "Latest" bubble beside it. The versions tab does list other major versions, but under the heading "Other modules containing this package", which is confusing.
Instead, pkg.go.dev could feature a prominent indicator on the landing page for a v0/v1 module that there are two successive major versions (v2 and v3), to funnel the user toward the latter.

Editor integration (gopls, goimports)

Go text editor integrations typically include a feature that automatically adds import statements to source files based on the mentioned identifiers. Because of Semantic Import Versioning, this also gives those tools the responsibility of choosing the major version of the imported module. In the case where there is no suitable existing requirement in the project’s go.mod file, these editor integrations could alert the user to the availability of newer major module versions. How this works is outside the scope of this proposal.

Proposal Co-authors

• @adg
• @peterbourgon

[bcmills]

The main problem with “on first add” warnings is that users often don't have control over when things are added: it's easy for a tool to accidentally do the thing that triggers the warning (and then not log the warning, because the command completed successfully), and then the warning is buried ~forever. (Compare rust-lang/cargo#5560.)

The editor integration seems more interesting, in that editors have the opportunity to surface low-priority information based on what the user is viewing rather than based on what they are doing.

[adg]

it's easy for a tool to accidentally do the thing that triggers the warning (and then not log the warning, because the command completed successfully), and then the warning is buried ~forever

Do you have a concrete example of this? I just use the go tool to manage my dependencies.

It seems a bit cavalier to dismiss the utility of this proposal just because some people or tools might ignore the output.

[bcmills]

Do you have a concrete example of this?

Consider the following scenarios:

• You run a command that produces a lot of output, such as go test all or go test -v ./..., then go back to editing your code (or go get a coffee or otherwise turn your attention from the go test command). By the time you look at the output (all tests passed!), the warning has scrolled well off the screen.

• You receive a pull request from an external user who copied the change from a local patch, and didn't feel like rewriting their patch (or even mentioning the newer version) when they mailed you the change.

• You added an import to a file, and now gopls is suggesting a change to your go.mod file to add the corresponding module (perhaps based on an internal, background go mod tidy run). You add it.

In all of these cases, the warning appeared at some point but was either ignored or missed entirely.

If it is important to surface out-of-date dependencies, I don't think a one-time warning is a good way to do that because it's so easy to miss the one time it appears. (Or, to put it another way: if it's unimportant enough that we shouldn't worry about the user missing the warning, then it's probably not important enough to emit the warning in the first place.)

[bcmills]

CC @jayconrod @matloob

[peterbourgon]

These proposals aren't intended to be perfect or exhaustive solutions to the complex problems they address — they're intended to be (substantial) improvements to the status quo. It is of course possible that a user could add a new module dependency to their project and then run the go tool in such a way that it would be easy to miss the messages we're proposing to add. YMMV, but I think it is much more likely, and far more common, that users add dependencies deliberately, and do pay attention to the results of the fetch.

[myitcv]

YMMV, but I think it is much more likely, and far more common, that users add dependencies deliberately, and do pay attention to the results of the fetch.

I commented over in #40357 (comment). I suspect in these days of gopls that the goimports-esque workflow is actually the most common.

Hence:

The editor integration seems more interesting, in that editors have the opportunity to surface low-priority information based on what the user is viewing rather than based on what they are doing.

is I think the best way to surface this information.

It seems a bit cavalier to dismiss the utility of this proposal just because some people or tools might ignore the output

@adg - I don't think this is a fair or particularly charitable interpretation of @bcmills' response. @bcmills made an observation about the problems associated with “on first add” warnings, cited an example, and then went on to agree with the proposal in the context of surfacing this via editor integrations. I don't think I would characterise that as "dismiss(ing) the utility of this proposal".

As some context, the golang-tools group has been discussing problems/solutions such as this since GopherCon 2018 (the group was largely established in the wake of the vgo release). I might well be biased, but based on previous experience the monthly calls are a good opportunity for discussion of these problems/solutions/options in the pre-proposal (design) phase.

[jayconrod]

This overlaps a bit with #40357, but I assume if a module author explicitly deprecates a major version with a comment in go.mod, then the go command wouldn't also show this notice.

I think some signal from the module author should be required to show a notice though, for two reasons:

1. If a new major version is available, it doesn't necessarily mean the old major version is deprecated. Even if no new features are added, an old major version may still receive bug fixes and security updates. Users might still depend on features in the old version that were removed. Basically, migrating to a new major version isn't necessarily the right choice for users. While the messages proposed here don't suggest an action, I feel like they imply that.
2. If we're telling users about a new major version, we should provide an action they can take to migrate. Because major versions are incompatible changes, there's nothing we can do automatically, yet. It would be better for the author to provide migration instructions in a deprecation notice. Or ideally, if migrations were automated (proposal: cmd/fix: automate migrations for simple deprecations #32816), we could tell people what command to run.

[peterbourgon]

I think some signal from the module author should be required to show a notice

The problem we're trying to solve is package consumers who intend to take the latest major version of a module, but select an old version due to unfamiliarity with the nuances of SIV. Making package authors opt-in to this notification wold subvert the intent and impact of the proposal.

If a new major version is available, it doesn't necessarily mean the old major version is deprecated.

The notification that a new major version is available is in no way a signal of deprecation of the current version. There is another proposal for authors who want to opt in to that stronger messaging.

If we're telling users about a new major version, we should provide an action they can take to migrate.

We initially had the notification include a command to make the upgrade, but went with this version in the end. Happy to switch back if that's the consensus.

[icholy]

If a new major version is available, it doesn't necessarily mean the old major version is deprecated.

The problem is that they look like warnings and will create more and more noise as a project gets older. Instead of putting it on a separate line, it could just be combined with the existing output.

$ 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.6.0 [v1.7.0] [latest v3.1.0]

[peterbourgon]

The problem is that they look like warnings and will create more and more noise as a project gets older.

We propose only a single line of output per dependency, specifically with a "note" or "notice" (read: not "warning") prefix, output only the first time the dependency is added to a project, and identifying only the most recent version of that dependency. I don't think this looks like a warning, nor does it create more noise over time.

edit: Also, to me, putting the notification inline implies some level of compatibility between major versions that feels misleading.

Instead of putting it on a separate line, it could just be combined with the existing output.

By itself, this would be insufficiently obvious to solve the problem we're trying to solve with this proposal.

[icholy]

nor does it create more noise over time.

Over time, as new major versions of your dependencies are released, more notices are printed.

[peterbourgon]

Over time, as new major versions of your dependencies are released, more notices are printed.

No, I don't think so. At least, the proposal doesn't intend so. Notices are only printed when a dependency is first added to a project at an older major version, or upgraded within an older major version tree. In other words, the trigger is not "a new major version of one of your dependencies is now available" but rather "you have added or upgraded a dependency to your project on a major version which is not the latest". And in all cases the notice only includes the most recent major version, not all major versions greater than the currently pinned major version.

[adg]

@bcmills wrote:

The main problem with “on first add” warnings is that users often don't have control over when things are added

The "on first add" part is just one part of this proposal. We also suggest printing the message when the user is looking to upgrade their module dependencies with go list -m -u all. That seems like an opportune time to present such a message. Do you agree?

@myitcv wrote:

I don't think this is a fair or particularly charitable interpretation of @bcmills' response. @bcmills made an observation about the problems associated with “on first add” warnings, cited an example, and then went on to agree with the proposal in the context of surfacing this via editor integrations. I don't think I would characterise that as "dismiss(ing) the utility of this proposal".

I apologise for my reaction, as opposed to a response. As someone who doesn't use the various editor integrations, I read @bcmills's response as a dismissal of my workflow. I still read it that way, but I recognise that the onus is on me to explain myself better here. Mea culpa.

the golang-tools group has been discussing problems/solutions

A little off topic in this thread, but: I would like to be involved but 15:30 UTC is 01:30 in my time zone, and I am ~never awake then. Real time chat does not work for me either; I struggle enough to stay on top of my asynchronous obligations as it is. I appreciate that there is some focused discussion on these issues, though. I will try to find some time to look through the minutes from previous meetings.

@icholy wrote:

Instead of putting it on a separate line, it could just be combined with the existing output.

@peterbourgon wrote:

By itself, this would be insufficiently obvious to solve the problem we're trying to solve with this proposal.

FWIW, I am not opposed to this suggestion. If the user is looking to upgrade their modules with go list -m -u all, then they are likely already scrutinising each line to see whether they should be ugprading.

I would make a small change to @icholy's suggestion, which is to include the full module path of the new major version, as it is different to the one printed on the line. So instead of this

github.com/peterbourgon/ff v1.6.0 [v1.7.0] [latest v3.1.0]

we should print something like

github.com/peterbourgon/ff v1.6.0 [v1.7.0] latest major version: github.com/peterbourgon/ff/v3 v3.1.0

But I do note that at that point things become crowded, and perhaps the two-line version in the OP is preferable.

[bcmills]

We also suggest printing the message when the user is looking to upgrade their module dependencies with go list -m -u all. That seems like an opportune time to present such a message. Do you agree?

I think the related proposal #40357 is probably a good idea.

However, especially given that proposal, I suspect that the log message from this proposal would be too noisy, for the reasons described by @jayconrod in #40323 (comment). I suspect that users will generally ignore the log message if it is not accompanied by instructions (or a tool!) to fix incompatible call sites, and even if they do know how to make the change it's not obviously worth the churn if the major version they are already using is itself still supported.

[adg]

On balance if we had to choose one proposal or the other I'd go with #40357, but I do think both proposal serve different purposes, and would work nicely together.

Updating between major versions is almost always going to the user to read some documentation and write some code. Whether they want to make the change is a judgment that only the consumer can make. Yes, we can't necessarily provide an easy upgrade path, but is that a reason not to offer them the information?

If the overwhelming concern is noise, perhaps we could try putting together a functional prototype of the command and see just how noisy it is on typical projects. IMO, such information isn't "noise" when I'm specifically asking about updates. But maybe it would become overwhelming? My gut says no, but I can't say for sure without trying it out.

[icholy]

gopls is great, but it should be possible to query this info without using third party tooling.

edit: is the intent to discourage publishing new major versions? (Not being facetious).

[peterbourgon]

@bcmills

I suspect that users will generally ignore the log message if it is not accompanied by instructions (or a tool!) to fix incompatible call sites,

One, this proposal is a response to the specific condition described in the problem statement, which is module consumers inadvertently selecting an old, typically v0/v1, major version of a module, when they intended to select the latest major version. This has happened to me, and to colleagues and peers, enough times that I was motivated to brainstorm, draft, iterate, submit, and re-submit this proposal with Andrew and Zach. Your critique seems to dismiss this initial condition as either invalid or so infrequent as to not be worth addressing. Is that your intent? Do you think this doesn't happen?

Two, the message is not printed only after the consumer has written code against the older major version which would need to be changed, it is also printed when the module consumer first imports the module. It's at that time that the proposal delivers the most value, in my opinion. Rather than wasting time integrating against an old version, the consumer can realize what happened and express their intent correctly.

Three, I personally have no expectation that module authors provide explicit upgrade instructions between major versions, and certainly not that there is any kind of tooling to do so automatically. Actually I've never heard this desire expressed by anyone I've ever interacted with, until now. Is this something that's common at Google? In any case, I don't think the lack of this theoretical tooling should impact the judgment of this proposal.

and even if they do know how to make the change it's not obviously worth the churn if the major version they are already using is itself still supported.

Is github.com/google/go-github v10.0.0 still supported, even though the latest version is currently v32.1.0? Is your position that someone who had inadvertently selected this ancient version would see the message suggested by this proposal as delivering net negative value?

[peterbourgon]

@myitcv @adg

the golang-tools group has been discussing problems/solutions

A little off topic in this thread, but: I would like to be involved but 15:30 UTC is 01:30 in my time zone, and I am ~never awake then. Real time chat does not work for me either; I struggle enough to stay on top of my asynchronous obligations as it is. I appreciate that there is some focused discussion on these issues, though. I will try to find some time to look through the minutes from previous meetings.

For the record, I intend to join the next meeting/s. I'll keep an eye on the wiki page for the next scheduled date, but please poke me in Slack when it's coming up, if you don't mind.

[zachgersh]

If the overwhelming concern is noise, perhaps we could try putting together a functional prototype of the command and see just how noisy it is on typical projects.

I generally love this idea. We don't need to speculate as to how noise when we can directly observe (and maybe have others here try this).

I personally have no expectation that module authors provide explicit upgrade instructions between major versions, and certainly not that there is any kind of tooling to do so automatically.

Really big plus one here. A major version upgrade, to me, means that an author will spend time understanding what about the library has changed in addition to how to upgrade their code to support it. Whether they then perform the upgrade themselves or there is some automation to do perform it doesn't prevent the need for that initial understanding.

[rsc]

It sounds like the main part of the disagreement here is about whether the module author should be able to keep this from happening. As written, this proposal does not let a module author who is perfectly happy maintaining v1 and v2 indefinitely stop the (implicit) "you should update to v2" messages every time a user starts using v1. Especially if v2 is not as capable as v1, that could be quite annoying for users, who will then complain to the author.

That is, this proposal forces a particular usage of module versions that is not strictly required to date.

In contrast, #40357 puts control over whether users are told about the new version in the module author's hands.

Do I have that right?

[peterbourgon]

@rsc

As written, this proposal does not let a module author who is perfectly happy maintaining v1 and v2 indefinitely stop the (implicit) "you should update to v2" messages every time a user starts using v1. Especially if v2 is not as capable as v1, that could be quite annoying for users, who will then complain to the author.

That is, this proposal forces a particular usage of module versions that is not strictly required to date.

I hope the proposed message doesn't imply, explicitly or implicitly, that the consumer should upgrade their version. I certainly hope the proposal isn't read as forcing an interpretation of module versioning. If there is a way to lighten the message to avoid this interpretation, I'd be happy to change it.

(It does seem both obvious and uncontroversial to me that, absent extenuating circumstances, a larger/newer major version of a software artifact should be preferred to a smaller/older one — but that's a philosophical discussion that we don't need to have here.)

It sounds like the main part of the disagreement here is about whether the module author should be able to keep this from happening.

I think it's important that this message isn't opt-in, but I'd be fine with it being opt-out.

[bcmills]

this proposal is a response to … module consumers inadvertently selecting an old, typically v0/v1, major version of a module, when they intended to select the latest major version. … Your critique seems to dismiss this initial condition as either invalid or so infrequent as to not be worth addressing. Is that your intent? Do you think this doesn't happen?

I think it does happen, but I think the appropriate point to intervene is usually earlier in the workflow. If a user has written an import statement, they got the idea to write that import from somewhere — a website (maybe pkg.go.dev or a code snippet from someone's blog), or a tool (perhaps goimports or gopls), or a snippet copied from some existing project.

If they got the import path from pkg.go.dev and didn't notice the version skew there, that's #37765 or perhaps #36969.

If they got it from goimports or gopls, then there may be a heuristic in those to fix. (If so, please file a separate issue.)

So that leaves a code snippet copied from some existing project, or perhaps a blog or tutorial. But in that case, why would you infer that they intended to use the latest version, rather than the version that the rest of their code snippet was written against? The rest of the code snippet is likely to not even work with a different major version.

[Merovius]

Personally, my workflow is a) I find the github (or whatever) page of the package I'm interested in, b) I type go get github.com/foo/bar (by hand) into my shell and c) I use bar.Baz() in my code and let goimports add the import statement.

So personally, I'd benefit from a warning on go get. Arguably, my workflow is bad and I am trying to be better about remembering major versions and type a more specific module path into my shell. But notably, I don't copy it from anywhere - I just type the name I think is correct.

[icholy]

@falco467 third party tools only.

[falco467]

@falco467 third party tools only.

that is quite sad, since this will lead to projects stuck on old major versions of dependencies.

[gaby]

Four years later and this is still open causing a lot of applications to not get updated with new major releases. This also affects dependabot as noted here dependabot/dependabot-core#2213

[lzap]

I also think this needs a revisit. I recently asked on the Gophers Slack channel and it seems that some people are confused that go get -u would do the job. I believe this is dangerous design.

For the record, there are already notes (warnings) as part of go get command:

$ go get -u ./...
...
note: imported by a module that requires go 1.21

Tho the argument of multiple major versions being considered stable and "good enough" by maintainers is a valid point. Now that is a deprecated feature in documentation, can we reconsider this feature?

[lzap]

One idea: if this feature is not accepted into the official Go tooling, it is possible to add a different feature into go get -u that would just check if there is a major version available during update of a package and if there is, it would insert go.sum entry nothing else. This way other tools could pick it up from here, for example a linter, and without accessing network it could immediately report this as an error or warning.

Example for a github.com/package/one that has github.com/package/one/v2 would make go get -u to create the following:

github.com/package/one v0.99.0 h1:xxxxxxxx
github.com/package/one/v2 v2.0.0 h1:xxxxxxxx

[gaby]

Adding some way for other tools to pick it up would be helpful, specially dependabot.

We took a look at our dependency graph and notice most users never upgraded our modules because it was a major release and they don't get notified.

For ex we have a package already on v3 and 80% of the repos using the package are still in v1.

[mitar]

I also love how npm-check-updates works with ncu -u mode, where it just updates the package.json (not package-lock.json) so that then you can inspect what has changed and decide what to do about it.

[rsc]

This proposal has been added to the active column of the proposals project
and will now be reviewed at the weekly proposal review meetings.
— rsc for the proposal review group

[benmathews]

Adding some way for other tools to pick it up would be helpful, specially dependabot.

We took a look at our dependency graph and notice most users never upgraded our modules because it was a major release and they don't get notified.

For ex we have a package already on v3 and 80% of the repos using the package are still in v1.

We have the same problem. As a hack, we run golangci-lint with a config like this in our ci pipeline

linters-settings:
  gomodguard:
    blocked:
      modules:
        - <old module>:
            recommendations:
              - <new module>
            reason: 'Uses of <old module> will cause a failing build starting XXX'

It has really lit a fire under people. Everyone bought in once the problem was explained and made visible.

[rsc]

Recapping this discussion because it has been such a long time.

In short, the proposal is to "notify" users of one module about a newer major version of that same module during various invocations of the go command, so that users know it might be worth updating.

There was a long discussion about whether "notifications" printed during go get count as warnings or not, especially given that the Go project avoids warnings, so it makes the proposal more palatable to say they are not warnings. Speaking as one of the people who set the “no warnings” policy, the definition of warning we meant in that policy is a message printed about something that may or may not be an actual problem, leaving the user to investigate and decide what to do. The messages being proposed here are warnings in that sense, and so from my point of view, we should not print them during go get.

There was also a long discussion about the meaning of the existence of a v2. Sometimes module authors create v2 and abandon v1. In that case, being warned about v2 could be helpful. But sometimes module authors create v2 and also keep maintaining v1. In that case, being warned about v1 is much less helpful. Therefore, the mere existence of v2 should not be taken as a reason to warn about use of v1. Some kind of explicit signal from module authors would be helpful here, like #40357, which at the time was also an active proposal.

There was also discussion about how much to encourage making newer module versions. One of the reasons for including /v2 in the module and package paths is that it makes the cost of creating a new, incompatible major version more explicit, which in turn discourages doing it unnecessarily. The discussion talked about whether adding these notifications would make v1->v2 transitions seem less remarkable than they should be.

I think it's fair to say that there wasn't complete agreement about any of these topics.

Since the discussion, #40357 has been accepted and implemented: module authors can add a // Deprecated: comment in the latest v1 go.mod if they want tooling to warn users that v1 is deprecated. The comment can say what to use instead, whether that's v2 or some new project with a different name.

This proposal was moved to likely decline in Sept 2020 saying:

This has been a long discussion and it seems clear that there isn't a consensus.
We have #40357 accepted, which addresses some of the same things, so it would make sense to do that first and see what's left.

Based on all that, it seems like this should be a likely decline.

@adg asked me to put the proposal on hold instead, because he had a partially written reply he wanted to finish. However, he never posted that reply, and now it's 2024.

It seems to me that we should move this lengthly proposal discussion back to likely decline at this point, for the same reasons as in Sept 2020, and move any specific suggestions about post-#40357 work to new proposals.

To guide those proposals, I will note the following:

• The design of modules and the overall policy of the Go project is that creating a new major version is a significatn, churn-causing event and should in general not be encouraged.

• Warnings (or “notifications”) during commands that mainly do something different, like go get, are simply not going to happen.

• Part of the proposal was to expose this information in go list -m -u, which currently lists the latest version of the existing module. As part of cmd/go: deprecate a major module version #40357, there is a new Module field Deprecated available during list. You can use it with something like:

  go list -m -u -f '{{if .Deprecated}}WARNING: {{.Path}}@{{.Version}} is deprecated: {{.Deprecated}}{{end}}' 
  

  It might make sense to add [deprecated] in the default output, to the end of a line for a module that has a deprecated note.

• @lzap remarked on the “note: imported by a module that requires Go 1.N” hint. That is not printed unconditionally. It is printed as an annotation on a “package X is not in std” error, so that for example if a user on Go 1.19 imports a dependency that says go 1.22.0 and then gets “package math/rand/v2 is not in std” error, the error also mentions that perhaps the problem is being caused by the dependency expecting a newer Go version. This general problem has been solved more completely by using those go lines as hard minimum requirements, so that annotation can be removed. I will send a CL for that. But again, it was never just a warning: it was a second line printed to try to help explain the error on the previous line.

• @lzap suggested adding “hidden” lines in go.sum that other tools could take as hints. Interesting compromise, but it is extremely unlikely that that kind of subterfuge is a good design decision. Also go mod tidy (which writes go.sum) does not currently do all the network access to obtain that information.

• @gaby wrote that "we have a package already on v3 and 80% of the repos using the package are still in v1." In general this can be completely fine, if v1 is maintained or if a final v1 was issued that is implemented as a wrapper around v3 (or around v2, and then the same for v2 around v3). On the other hand, if v1 is marked Deprecated, that would be more concerning. In that example, is the v1 marked Deprecated?

[mitar]

@rsc: Thank you for great summary.

Based on it I would propose that Go simply add a new sub-command to go mod, something like go mod check or go mod upgradeable which would check existing dependencies for:

• Deprecations.
• Available minor versions.
• Available major versions.

It could print that out in readable format or in JSON format (so that other tools could take that as input). I think this would allow then various plumbing with CI and other tooling to get warnings, errors, notifications, e-mail notifications, whatever. It would also not pollute all other go commands with messages people might not expect. I can imagine then somebody making a linter for golangci-lint which would require that everything is on the latest version. Or whichever policy you want.

The command could then also be extended in the future (suggesting fixes, adding additional checks - like suggesting which version changes might reduce the number of different versions in the program) without adding noise to existing other commands.

[billinghamj]

I think this is practically at odds with how major versions are actually used, especially with the pervasiveness of semver. To give one (admittedly fairly extremely) example, stripe-go is currently on v78 🙄 - https://github.com/stripe/stripe-go

Whether it's right/wrong to output info at particular times, the reality is that it is very common for projects to move to a new major version, to not continue maintaining their previous ones, and to not deprecate their previous ones (as soon a new major version is out, it's very unusual for a new "older" tag to ever be created)

Regardless of the theory, an additional command to indicate where new versions are available would be practically very helpful in staying up-to-date

[rsc]

Based on the discussion above, this proposal seems like a likely decline.
— rsc for the proposal review group

[gaby]

@rsc That doesnt help the Golang ecosystem at all. None of the tools take into account the "// Deprecated", a warning is not enough.

Take into account dependabot, it doesn't notify about new major versions, it has no way of know either.

[KenjiTakahashi]

I have to agree with @billinghamj here.

It is also worth noting that there are a number of projects already past-v1, which have moved on to the next major before the deprecation "feature" even existed.
Expecting that all of them are now gonna go back and retrospectively mark earlier versions as deprecated is, frankly, wishful thinking.

In general, basing discoverability solely on an explicit action from every (relevant) project maintainer is not very realistic.

[rsc]

The fundamental disagreement here is about whether the existence of v2 means that v1 should be implicitly considered deprecated and actively warned about. I wrote in the summary:

There was also a long discussion about the meaning of the existence of a v2. Sometimes module authors create v2 and abandon v1. In that case, being warned about v2 could be helpful. But sometimes module authors create v2 and also keep maintaining v1. In that case, being warned about v1 is much less helpful. Therefore, the mere existence of v2 should not be taken as a reason to warn about use of v1. Some kind of explicit signal from module authors would be helpful here, like #40357, which at the time was also an active proposal.

This remains true. Yes, some packages issue new major versions without marking old ones deprecated and should have done that. But others support both. We should encourage packages like stripe to mark old ones deprecated, and then tooling can do the right thing. (Or not. Maybe stripe supports the last 5 versions and they can mark the ones older than that deprecated. I don't know. But this gives them the ability to say exactly what should and should not be used.)

[zikaeroh]

There was also a long discussion about the meaning of the existence of a v2. Sometimes module authors create v2 and abandon v1. In that case, being warned about v2 could be helpful. But sometimes module authors create v2 and also keep maintaining v1. In that case, being warned about v1 is much less helpful. Therefore, the mere existence of v2 should not be taken as a reason to warn about use of v1. Some kind of explicit signal from module authors would be helpful here, like #40357, which at the time was also an active proposal.

Isn't this is self defeating? Anyone proactive enough to use a new "outdated" signal can already mark their old modules as deprecated today. Conversely, anyone who's already abandoning old versions will also not use a new explicit signal either, and it doesn't seem straightforward for those kinds of projects to resurrect old versions just to mark them as outdated/deprecated (find the last commit of a specific major version line, branch off, commit some new thing, publish again). So, even if modules could be marked as outdated, it doesn't seem to leave things better off.

[rsc]

No change in consensus, so declined.
— rsc for the proposal review group

[mitar]

The fundamental disagreement here is about whether the existence of v2 means that v1 should be implicitly considered deprecated and actively warned about.

I think my proposal above with 11 upvotes goes away from this disagreement: we do not do such consideration and we do not do any warnings. There is just a simple tool which tells you that there are other higher versions available. It is on you (or your wrapper tools) to decide what to do about that then. I haven't seen any counter arguments against that?

[gaby]

@mitar Agree, and having a command like that would allow tools like dependabot, etc to alerts projects about new major versions. Most languages support this (Python for example is great at this), I don't understand why the Go team doesnt consider this.

Should Go projects instead use plain semver for major releases instead of github.com/pkg/pkg/v2 ?

[Merovius]

@mitar I'd suggest filing that as a new proposal, so it can be discussed on its own merits, instead of throwing together two different discussions.

[mitar]

Done: #67420