How to troubleshoot go module issues

Refer here for all Go modules questions

Q: There is a circular dependency that I did not intentionally create?

A: First trace the output to find out the circular path. See if you can move some functions/constants into other packages. If not, consider making the entire part a new package/subpackage. If it's a test circular dependency, consider putting current folder's *_test.go into a subdirectory test/.

Q: Different module dependencies are conflicting with each other, with either an incompatible or duplicate error?

A: Use go mod why <offending-module> to see which two (or more) files are using conflicting versions. If necessary, make updates in the base modules.

Q: What's the general guideline for updating modules (mostly upstream from IPFS)?

A: They should normally only be updated when go-btfs pulls upstream updates from go-ipfs. In some cases, bug fixes need to be applied to individual modules without updating from go-ipfs.

Q: go mod tidy keeps deleting/adding modules in go.mod that I do not understand?

A: Before submitting a PR, always trust the version go mod tidy gives you. During local debugging/testing, go may add additional dependencies that are not intended for release.

Q: There is always an indirect dependency that I cannot remove?

A: Use go mod why <that-module> to see who's pulling it in. If it's from a _test.go file it's OK to ignore. If it's from a normal .go please update dependency paths accordingly.

Q: How to update a particular module?

A: The safest way is to edit the version in go.mod directly, save, then run go mod tidy. However, if you need to grab a specific branch/version/latest, you can go get <module-path>@<version>. Note that you should very rarely need go get -u because it updates all direct and indirect dependencies [ref].