How to release updated packages for Go Mod / pkg.go.dev consumers?

Question

How does one tag their repo, and get it to show up for go mod and/or pkg.go.dev?

I have converted one of my packages to go mod. However, it seems the go mod tool itself can only see very old versions of my package.

EDIT: I just noticed that my old versions had a "v" prefix, whereas my newer tags do not have the "v" prefix.

Is that the root problem? Where is that hard requirement documented?

---

My package in question: https://github.com/eduncan911/podcast

And my tagged releases: https://github.com/eduncan911/podcast/releases

1.4.1
1.4.0
1.3.2
1.3.1
1.3.0 <- this is the current version Go Modules sees available

However, pkg.go.dev shows:

v1 – github.com/eduncan911/podcast
v1.3.0 – Feb 19, 2017
v1.1.0 – Feb 6, 2017
v1.0.0 – Feb 5, 2017

The FAQs on https://proxy.golang.org/ says:

I committed a new change (or released a new version) to a repository, why isn't it showing up when I run go get -u or go list -m --versions?

In order to improve our services' caching and serving latencies, new versions may not show up right away. If you want new code to be immediately available in the mirror, then first make sure there is a semantically versioned tag for this revision in the underlying source repository. Then explicitly request that version via go get module@version. After one minute for caches to expire, the go command will see that tagged version.

So, I tried that:

$ go get github.com/eduncan911/[email protected]
go: cannot use path@version syntax in GOPATH mode

Guessing this means I need to be in a repo or Go project; so, I created one:

$ cat main.go
package main

import (
        "fmt"
        "github.com/eduncan911/podcast"
)

func main() {
        fmt.Print(podcast.MP3)
}

Changed to this directory, ran go mod init, and ran it again:

$ go mod download github.com/eduncan911/[email protected]
go: finding github.com/eduncan911/podcast 1.3.1
$ go mod download github.com/eduncan911/[email protected]
go: finding github.com/eduncan911/podcast 1.3.2
$ go mod download github.com/eduncan911/[email protected]
go: finding github.com/eduncan911/podcast 1.4.0
$ go mod download github.com/eduncan911/[email protected]
go: finding github.com/eduncan911/podcast 1.4.1

Ok, no response and return to prompt. Maybe I'm onto something...

$ go run main.go
go: finding github.com/eduncan911/podcast v1.3.0
go: downloading github.com/eduncan911/podcast v1.3.0
go: extracting github.com/eduncan911/podcast v1.3.0

Doh.

$ go mod graph
github.com/eduncan911/podcast-test github.com/eduncan911/[email protected]
github.com/eduncan911/podcast-test github.com/pkg/[email protected]

Maybe I need to download explicit versions, like the FAQ said module@version.

I edited the go.mod and specified 1.3.1. Then:

$ go mod download
go: github.com/eduncan911/[email protected]: reading github.com/eduncan911/podcast/go.mod at revision v1.3.1: unknown revision v1.3.1

My last attempt was to go back to the FAQ statement and run go get module@version like it said:

$ go get github.com/eduncan911/[email protected]
go: github.com/eduncan911/[email protected]: reading github.com/eduncan911/podcast/go.mod at revision v1.4.1: unknown revision v1.4.1

Note, I kept changing versions in-between some of those statements above. But everytime, it was a version that was not present.

I've waited several hours and retried many of these statements for any caching to be cleared.

Thanks in advance!

Yardley

Answer 1

There are two issues with the OP.

1. Go Mod ignoring package tags not prefixed with v as @Flimzy pointed out
2. pkg.go.dev not showing/exposing new versions as soon as it is tagged, relying on the "community" to request a newer version before one is found

The first is an easy fix - retag everything with the v prefix.

The second can be fixed by adding this to the CICD pipeline:

curl https://sum.golang.org/lookup/github.com/eduncan911/[email protected]

It's the most reliable way to force pkg.go.dev to update and makes the new tag available immediately for the rest of your pipelines to run and test. It works by forcing pkg.go.dev to obtain the hash for that particular version. If the version doesn't exist, it will fetch it - and then hash it. Hence, adding to the Go Mod data source.

I have to caution that it's not very well documented, so the API could change overtime. They want you to use the Proxy command; but, I didn't have much reliability with it over many test publishing. However, the curl command above worked 100%, everytime, and was made available immediately (resetting caching).

Yardley

Answer 2

Is that the root problem? Where is that hard requirement documented?

Yes, it is required. From the Go wiki (emphasis added):

Modules must be semantically versioned according to semver, usually in the form v(major).(minor).(patch), such as v0.1.0, v1.2.3, or v1.5.0-rc.1. The leading v is required. If using Git, tag released commits with their versions. Public and private module repositories and proxies are becoming available (see FAQ below).

Anodic

Thanks. However, once I did that they still didn't show up and required manual go mod download after editing a sample go.mod. Is there some other way to get it to show the new versions without having to add fake project and go mod download command into my CICD pipelines after a tag is created? Seems very much overkill. – Yardley

@Yardley the docs you quoted yourself in the question state "In order to improve our services' caching and serving latencies, new versions may not show up right away." That doesn't mean they won't show up ever. What you've described forces it to update from repo immediately, rather than whenever its regular cache refresh might run. – Fondly