what does "+incompatible" suffix mean in Go github versions?

Question

I am considering upgrading go-github from v17.0.0+incompatible to v28

I notice some versions that go-github released has a +incompatible suffix, especially for the v1 category. What does that entail? I am guessing version with +incompatible are incompatible with the newer/older version?

In general, when updating a third party dependency, how can I know if upgrading to the newer version is safe? Do I just have to read through the change logs?

Answer 1

The +incompatible suffix in go.mod is used when Go Modules is dealing with a dependency that is not a Go module, i.e. it doesn't have a go.mod file.

This usually occurs when you are importing a package that has not yet adopted Go Modules or is in a version that predates the adoption of Go Modules. Go Modules can still work with these packages, but the +incompatible suffix is added to indicate that the package is not a Go module.

Answer 2

Go in general does not want you to use the same import path for multiple incompatible versions of a project. This is so that one dependency can use one major version of a module and another dependency can use another.

This syntax indicates that the repository is not using a suffix for their module paths for a non-v0, non-v1 version, and bypasses the logic in the module code that does semantic import versioning. The documentation about this functionality is available on the Go website.

Since going from one major version to another is a breaking change in semantic versioning, you'll need to determine out of band whether or not they're compatible. The +incompatible suffix doesn't implicitly denote this, but going from v17 to v28 does. So changelogs might be a good idea, or you could just update and run your tests if you're confident in your testsuite.