Unusual go directive in go.mod

[mx-psi]

The top-level go.mod uses 1.21.0 as its go directive

ebpf/go.mod

Lines 1 to 3 in 32b95e4

	module github.com/cilium/ebpf
	go 1.21.0

This is an unusual choice that forces every Go module dependent on cillium/ebpf to also specify the bugfix version on its go directive.

As far as I can tell, there is no evidence that using the bugfix version is recommended or encouraged by the Go authors or Go compiler contributors:

• The go.mod file reference has go 1.14 as an example, no examples with the bugfix version, and indicates that the go directive specifies semantics (which should not change in bugfix versions)
• The comment here b3432fb#commitcomment-138898478 points to cmd/go: mod tidy reports toolchain not available with 'go 1.21' golang/go#62278, which doesn't seem to explicitly advocate for adding .0 in all cases, only as a workaround to a specific issue

What is the rationale for specifying the bugfix version?

[lmb]

We've discussed this on the Slack channel, the long and short of it is that this is a change in upstream behaviour. So while the version looks odd it seems to be the correct choice.

[mx-psi]

You can request an invite to the Slack here: cilium.herokuapp.com

Thanks, I was able to read the Slack conversation now. The only additional piece is golang/mod@766dc5d, which refers to the toolchain directive, not the go directive, which is irrelevant here.

bcmills was part of the Go team until recently: golang/go#62278 (comment)

bcmills comment above that one golang/go#62278 (comment) helps elucidate that this is valid and that it is recommended in certain situations when using toolchain, but not that it is recommended in general.

Someone one the team also closed the issue I linked

Yes, that would be golang/go#62278 (comment), which again refers to the specific situation of using GOTOOLCHAIN, not in general.

You should argue your case in the upstream issue if you disagree.

There is nothing to argue about upstream, since this is not recommended upstream. This is entirely an issue with cillium/ebpf.

In any case, I got the information I needed as to why this change was done, thanks again: I appreciate the links and further context, even if we don't agree :)

[lmb]

As far as I can tell, there is no evidence that using the bugfix version is recommended or encouraged by the Go authors or Go compiler contributors

There is nothing to argue about upstream, since this is not recommended upstream. This is entirely an issue with cillium/ebpf.

Seems like this free piece of software is somehow causing you a problem. Why not try it with a bit of constructive feedback? It'll get you farther.

• You are currently doing X
• That is causing a problem Y
• You've tried solving the problem by doing Z, but maybe it doesn't work
• Could we do FOO instead?

Here are my constraints:

• go mod tidy should not make any changes.
• The minimum required language version should be the oldest supported Go release. So 1.21 currently. Trying to use the module from something older than that should give an error.

The smallest change I could come up with that satisfies these is to add .0. What would you rather have us do? Why is it a problem if you have to specify a .0 in your go.mod?

Finally, seems like we aren't the only ones specifying 1.21.0: https://sourcegraph.com/search?q=context:global+file:%22go.mod%22+%22go+1.21.0%22&patternType=keyword&sm=0 I doubt we're in the dependency tree of all of those modules.

[mx-psi]

Let me take a step back. I apologize for the perceived lack of constructiveness.

You are currently doing X

I am adding cilium/ebpf as an indirect dependency to a piece of free software I maintain, which has around ~700 dependencies already. This piece of software has the exact same constraints as yours in terms of go mod tidy and Go version compatibility.

That is causing a problem Y

Adding cilium/ebpf forces me to switch from go 1.21 to go 1.21.0. It also forces all downstream dependencies of my project to adopt go 1.21.0, which I will need to educate, and people like me will come and ask why we are doing this.

While this change works, it forces me to do something that is:

• not documented in the Go docs, go.mod file reference or Go blog or used by the Go stdlib itself
• only mentioned in an issue on the golang/go tracker as a workaround for using toolchain, which is a feature meant to be used only when something is the main module (i.e. you are building an application, not a library)
• unusual within the Go ecosystem (not unheard of as you have shown, but definitely not the usual in Go libraries as the fact that none of the other 700 libraries I use show)

You've tried solving the problem by doing Z, but maybe it doesn't work

There is no workaround for this: if I am to depend on cilium/ebpf, directly or indirectly, I need to update the go directive.

Could we do FOO instead?

My ask would be to replace go 1.21.0 by go 1.21.

Doing this locally on a copy of cilium/ebpf works and does not cause any changes when running go mod tidy (I tested this with versions 1.21.0 and 1.22.0 of the go binary). From a cursory look, it does not seem like this would cause any issues on CI either.

[lmb]

Thanks for the context, I appreciate it! I'm pretty sure that I tried go 1.21.0 originally and that something complained.

In terms of official doc, I'm reading https://go.dev/doc/toolchain Some choice quotes (not in order):

The go line declares the minimum required Go version for using the module or workspace.

Then, from "Go versions":

Released versions of Go use the version syntax ‘1.N.P’, denoting the Pth release of Go 1.N. The initial release is 1.N.0, like in ‘1.21.0’.

Before Go 1.21, the initial release of a Go toolchain was version 1.N, not 1.N.0, so for N < 21, the ordering is adjusted to place 1.N after the release candidates.

I think this is why 1.20 works but 1.21 doesn't. There are also many examples using go 1.21.0 in the document.

Overall, is this change worth all of this effort? As far as I can tell the only downside is that the version number has a format that people are not used to. But does it prevent doing something that is possible with go 1.21?

Feel free to put up a PR, then we can run it through CI and see where it breaks. Maybe that is instructive.

[mx-psi]

In terms of official doc, I'm reading go.dev/doc/toolchain S

Right, I think 1.21.0 is the right choice if using toolchain. I guess a crux of the disagreement here is that https://go.dev/ref/mod#go-mod-file-toolchain says

The toolchain directive only has an effect when the module is the main module [...]

and I take that to mean that toolchain (and related rules) is only meant to be used for applications, not for libraries like cilium/ebpf

Feel free to put up a PR, then we can run it through CI and see where it breaks. Maybe that is instructive.

Let's see if it breaks! I filed #1441