Proper support for go modules.

[roidelapluie]

This pull requests makes Prometheus go-mod compatible.

The general idea is to release the Prometheus libraries as v0.x
releases, next to the v2.x tags used by end users.

This is done by mirroring Prometheus 2.x tags with Prometheus 0.x tags.

When v2.X.0 is released, we would release v0.X.0.

Pre-go mod versions are retracted from go.mod. This is not nice but
should work.

Only v2.x tags will be built and released by CI. v0.x.x tags would just
be normal tags in the repo, not promoted as releases.

Signed-off-by: Julien Pivotto roidelapluie@inuits.eu

[beorn7]

I am cautiously optimistic that this actually works as described. I think we should document the approach more clearly in the RELEASE.md and perhaps put a paragraph into the README.md to tell users of Prometheus as a library what's going on and why the Prometheus module is versioned weirdly.

What does everyone else think? It would be especially interesting to learn if this is helpful for Cortex/Thanos folks. @bwplotka @pracucci

[beorn7]

I have no idea why the CodeQL analysis fails.

[roidelapluie]

I have no idea why the CodeQL analysis fails.

CodeQL is built with go1.15. Retract in go.mod is a go1.16 thing.

[beorn7]

I see. Can we update CodeQL?

[beorn7]

\o/

[roidelapluie]

Can/should we move on with this?

[metalmatze]

Yes, seems good to me. 👍

[beorn7]

As said, I like it. But we are doing this mostly for people using prometheus/prometheus as a library, so it would be good if some of those could confirm that this would help them. I guess @metalmatze counts as Thanos. Someone from the Cortex/Mimir side would also be good. @pracucci or @bboreham perhaps?

Everyone involved in issues #8852 #8513 #8417 #7991 #7663 #6048 #5356 might also have an opinion. I guess mentioning those issues here pings them all… :->

[metalmatze]

Both for Thanos and Parca having versioned sub modules would be great as both projects use Go mod replaces to depend on Prometheus. Is this what you're asking @beorn7?

[beorn7]

I'm asking if this PR would improve the quality of your developer experience.

having versioned sub modules would be great

IIUC this does not introduce versioned sub-modules. It introduces a v0.x Go module versioning mirroring our v2.x product versioning and hides all the v1.x and the subset of relevant v2.x tags so that the Go module system will only see the latest v0.x version tag as long as you don't explicitly ask for a v2+.

The cool thing about is that by using v0.x (rather than v1.x), we are not breaking any contract if we have breaking API changes in a release because we are still pre-v1 from the PoV of Go Modules.

[metalmatze]

Yes, this will definitely improve the situation. I don't think we even care for having the exact same semver.

Doesn't get much worse than this, honestly:
https://github.com/thanos-io/thanos/blob/58ffc8f4280bb1d7e132ec801ee47d8f2b9c67f4/go.mod#L224-L225
https://github.com/parca-dev/parca/blob/47c9e142a3c443de252696fb614335518013f746/go.mod#L57-L58

[beorn7]

Reiterating on what I said above: It would be cool to have a bit more of the context explained in RELEASE.md and add a note close to the top of the README.md summarizing the effect for Go Modules user (most importantly that you will use the code released as Prometheus 2.x.y if you are seeing v0.x.y in your go.mod file).

[rfratto]

This would make things much easier as a downstream consumer. However, I'm concerned about whether this would confuse users.

I already get a lot of questions about what version of Prometheus Grafana Agent uses since they all display as being part of the most recent 1.X release. I fear that having synchronized 0.X and 2.X releases will still confuse users in this way; thinking that a project is many major versions behind.

Personally, I would rather see a single v2.X tag with the module path changed to github.com/prometheus/prometheus/v2, and for it to be strongly communicated to consumers that the module is subject to breaking changes at the API level without increasing the major version number.

[prymitive]

I import Prometheus modules (mostly parser) in https://github.com/cloudflare/pint and at the moment when there's a new Prometheus release I have to take the commit sha of that release, put it in go.mod as the version to use (github.com/prometheus/prometheus abc1234567) and the run go mod tidy to turn that into "proper" version go modules use + add all required deps.
I would love if dependabot was able to make a PR for me instead, although it's not really much problem to do it every few weeks. The main problem is that it's hard to decipher which version I'm really using just by looking at the go.mod file, since it's a really just a sha at the moment, rather than any meaningful semver string.

[roidelapluie]

Switched branch to release-2.35 and added an explanation.

[beorn7]

Looks good from my side. I understand @rfratto's point, but this is just a trade-off: confusion of breaking the semver contract on a code/API level vs. the confusion of having a Go Module version different from the version of the product releases. I value keeping the semver contract more strongly.

BTW, we still need an explanation in the README.md ("If you are using this repository as a Go module, note that…"), but we can add/discuss that later.

[Nexucis]

Everyone involved in issues #8852 #8513 #8417 #7991 #7663 #6048 #5356 might also have an opinion. I guess mentioning those issues here pings them all… :->

Actually it doesn't ping everyone when you are listing the issues like that. But it's cool you took the time to list all of them related to the go module @beorn7, because pretty sure we could close them with a nice message saying it has been fixed thanks to this PR.

@roidelapluie I'm totally fine to merge this in the current release. I think like @beorn7 we need a short explanation in the README.md explaining how to import Prometheus in your project.

[roidelapluie]

let's merge this, see how this works when we release, and ping people next week on the issues. thanks all!