Keeping your Go modules compatible

there's something that I just don't get about golang modules, I don't know what it is but they don't click with me

it might well be something tacit that golangers learn from each other directly? or otherwise it's so obvious and simple and I just haven't realized?

it feels like it's the kind of thing that just clicks one day possibly after a few years

IMO the documentation isn't there yet, it lacks a Q&A webpage or something short and giving the main how-tos in a succinct manner: How to create a module? How to bump a package version? How to use a specific package's branch? What to do if there is a conflict because a package used by another package messed up its compatibility?

The current first Google result when looking for "go modules" is https://blog.golang.org/using-go-modules which is a very verbose post starting with "This post is part 1 in a series of 5 parts". Not very engaging.

In one year I've accumulated a few snippets that I use regularly and get used to `go mod` but it was painful at the beginning. I wish I could have contributed to this topic but Go is most of the time a language that only requires to read pkg.go.dev and the main blog posts to know what's next and this Go modules workflow is, like gopls, something that doesn't currently have a good place to be documented AFAIK.

Edit: Thaxll's comment gives a very nice URL to learn about Go modules, still too much for a beginner IMHO but it has a Q&A part that goes very deep.

You're not alone. I've been writing go since before 1.0, and can handle modules/packages in _any other language_ fine, yet go's regularly leaves me stumped.

A little while ago we were hitting yet another issue with dependencies related to version pinning at work. I tried to divine what the disparate versions mean, and came up with this flow chart from a legalistic reading of stack overflow issues [1] and the go modules doc [2]:

  has the package opted into go modules (i.e. is there a go.mod?)
    yes
      does the repository use semver?
        yes
          is the major version  normal versioning, e.g. github.com/stretchr/testify v1.3.0
            no
              => when importing, we need add /vN at the end, e.g., import "github.com/my/mod/v4", and in go.mod it will behave like github.com/my/mod/v4 v4.1.0
        no
          => pseudo-versioning will be used, e.g. github.com/kolo/xmlrpc v0.0.0-20190717152603-07c4ee3fd181
    no
      does the repository use semver?
        yes
          is the major version  pseudo-versioning will be used, e.g. github.com/kolo/xmlrpc v0.0.0-20190717152603-07c4ee3fd181
            no
              => version will be marked as incompatible, e.g. github.com/zeromq/goczmq v4.1.0+incompatible
        no
          => ???

I still don't know if this is right. But that's not really the point. I think the go authors painted themselves into a corner with such an anemic initial release. Now that they're trying to address shortcomings, the complexity is blowing up to handle the very large/diverse ecosystem. It reminds me a lot of java around 1.4 when they added in generics. In the long-run it was the right move, but man was it painful.

1: https://stackoverflow.com/a/57372286 2: https://github.com/golang/go/wiki/Modules

In college we referred to this same idea (among my peers who were going on through graduate studies, particularly PhDs) as "academic incest", where you aren't sufficiently exposed to a diverse enough set of ideas and end up too narrowly focused or clouded in your judgment.

Ways to overcome it include: moving (in academics, accepting a fellowship at other institutions; as a professional, change jobs); observation (keeping abreast of the latest trends outside your immediate environment and field); community participation (attending conferences, symposia, and similar things; or even forums like this).

But ultimately it requires a recognition that your views, knowledge, and beliefs are, necessarily, constrained by your experiences and that you sometimes have to seek out novel experiences or the experiences of others to change yourself. If you lack the drive for either, or too great a confidence in your own present state, then you're going to be stuck.

Modules have nothing to do with comparable structs. It's just that making a comparable struct uncomparable could break users of your API, so it's something to be on the lookout for if you value backcompat. (The module system ensures that users will get the version of the code they want; you only have to worry about backwards compatibility if you expect users to upgrade to your new version.)

There are millions of ways to break users with an update that machines can't detect. For example:

Old version:

func Lt(a, b YourType) bool { return a New version:

func Lt(a, b YourType) bool { return a >= b }

This is not specific to Go.