Is it a good idea to use tool directives?

[gabizou]

Given Go 1.24 has added tool directives, we can now "pin" the version of Orchestrion in a go mod file, which avoids having to use go run directives or go install and instead use go tool orchestrion.

My question is around are there any downsides to running orchestrion in this manner, when it comes to using CI and developer experiences that could help ensure a reproducible run, when comparing to the GitHub Action that performs an install and updates various go environment flags?

[RomainMuller]

I would definitely prefer using a tool directive, and have considered making this the default behavior of orchestrion pin when the go.mod directive has go 1.24.0 (or later)... It's definitely a "cleaner" flow than go run github.com/DataDog/orchestrion go build, etc... and I am a long time believer that everything around your app should be in your go.mod file (dependencies, test dependencies, tool dependencies, linters, etc...).

The ONE thing I am not sure about yet, is how tool directives interact with the toolchain version... Orchestrion needs to be built with a version of the standard library that is at least as recent as your go directive indicates (for it needs to parse the .go files with the standard-library-provided AST).

[gabizou]

The ONE thing I am not sure about yet, is how tool directives interact with the toolchain version... Orchestrion needs to be built with a version of the standard library that is at least as recent as your go directive indicates (for it needs to parse the .go files with the standard-library-provided AST).

I believe the operational module -> toolchain semantics apply as if orchestrion is pulled in as a dependency and compiled based on the toolchain that satisfies the go directive.

making this the default behavior of orchestrion pin when the go.mod directive has go 1.24.0 (or later)

I was considering the same thing using build constraints like //go:build !go1.24 to use the "old way" and having a //go:build go1.24 version of the file to use the new tool directive. The benefit as well is being able to perform tool upgrades per the docs:

The tool meta-pattern provides a way to perform operations on all tools simultaneously. For example you can upgrade all tools with go get -u tool, or install them all to $GOBIN with go install tool.

[gabizou]

Also, considering that it would be a good piece of documentation to use go tool directives in Go 1.24, would it also make sense to update the docs in retrospect? Is that something that I'd be able to contribute?