Documentation - Installing mage / managing it as a tool dependency

[thaney071]

Background

There are several open issues related to installing, updating, or managing mage as a tool dependency. Some are resolved through previous updates to the repo READ.me and web content. Others are because of still outdated information in the repo.

I have collected what issues I could find to compile them in one place since they are all generally all related and can be resolved through updating the documentation. I also wanted to start the discussion about any potential docs change / updates.

I have also collected several issues related to managing go tools. This is more in reference to a few issues with the zero installation and updating mage.

Related Issues

Issue	Status
#325	Need Doc Update
#339	Need Doc Update
#334	Need Doc Update
#302	Need Doc Update
#234	Possibly related
#235	Possibly related
#229	Needs To Be Closed

Zero install and general tool management

One of the documented ways to use mage is the zero install method. Issue #325 has been open about updating the docs to not use the ignore build tag since go mod tidy does not evaluate files with that tag.

This pattern is basically the recommended way to manage tool dependencies in Go for now (See link in Background section). It works for most use cases but there are several issues about edge cases that it does not:

• cmd/go: document using -modfile to record tool versions without interfering with main module dependencies golang/go#33926
• cmd/go: clarify best practice for tool dependencies golang/go#25922

It seem there is not any consensus on what is the current best practice, but I found some ideas at least:

• separate go.tools.mod file: cmd/go: clarify best practice for tool dependencies golang/go#25922 (comment)
• a tool dedicated to solving this problem: https://github.com/bwplotka/bingo
• an example setup using a separate module: https://github.com/nordicdyno/golang-tools#motivation
• since 1.17 Go supports running with a version go run example.com/cmd@v1.0.0, which could be used in the Makefile (this seems to me to be the best approach, with the main downside being that golangci-lint version would be duplicated - in the Makefile and docker-compose.yml)

While overall not everyone in go agrees, The recommended best practice is to use a tools.go as mentioned In the background section.

For now, IMO it would be best to reference the go wiki for tools in addition to documenting the bootstrap.go. Potential have a reference to here about possible changes to tool management that may affect the zero install option later.

I will try to keep this updated and spend some time this month writing the updated docs.

[natefinch]

Excellent write up, thank you. I agree that we need to change the zero install example to not use ignore.

And we should clean up those issues so they're not spread all over. I really appreciate the time you've put into this.

[thaney071]

@natefinch, Can you assign me the issues I linked in this Discussion?