getting newer versions to appear on pkg.go.dev

[jba]

This is the pkg.go.dev team responding to the feedback left today, which reads:

Note the "Published: Jun 30, 2015". Our master branch gets updates nearly daily, making this page nearly 5 years out-of-date. We also have published releases, the most recent stable release being last October. Not sure which you try to use.

The Go module system recognizes module versions by semantic version tags on the repo, as described in the go command doc and this blog post. We look at those tags (indirectly, via the module proxy index), and we consider the latest one to be the highest (in the semver sense) "release" tag. A release tag is of the form vX.Y.Z. If there is a higher prerelease tag (vX.Y.Z-blahblah) or pseudo-version, we remember it but don't consider it "latest."

So by our definition, the latest version of your repo is v1.1.3, published June 30, 2015.

If you were to tag your current master v1.1.4, then fetch it through the proxy using go get, we would soon update our page.

Hope this helps.

[ocket8888]

Well our project neither now is nor ever was a go module, nor does consist even in part of go modules. There has been talk of using the go module system, but one of our dependencies has issues with the newer versions of Go that support modules, so we can't at this time. We likely won't change the tag naming scheme until such time that it becomes necessary (that is, when we switch to the Go module system).

[zrhoffman]

v5.0.0 now shows up on pkg.go.dev, but as v5.0.0+incompatible, so v1.1.3 is still listed as the latest version. In order to get +incompatible removed, I think we would need to tag v2.0.0, v3.0.0, and v4.0.0.

[ocket8888]

I don't think creating new tags would be a big deal - if we really want to keep the practice of naming our releases like RELEASE-{{VERSION}} (which I don't think is mandated by Apache or anything) then we could totally still do that, just augmenting with more tags.

[jba]

In order to get +incompatible removed, I think we would need to tag v2.0.0, v3.0.0, and v4.0.0.

No, you need to have a go.mod file.

See https://golang.org/cmd/go/#hdr-Module_compatibility_and_semantic_versioning, especially the paragraph beginning "Code written."

[ocket8888]

Welp. Looks like this'll need to wait for #5229

[ocket8888]

now that #5229 is closed, looks like the next major release will close this (and #5488). I don't think this will make it into 5.1, unfortunately.

[zrhoffman]

Now that Traffic Control 6.0.0 is released and v6.0.0 (which has a go.mod file), exists, v6.0.0 is still not shown on pkg.go.dev. Instead, as the default version, pkg.go.dev shows v5.1.3+incompatible, the latest tag that does not have a go.mod file.

If I understand semantic versioning correctly, in order to get our latest godocs to show up on pkg.go.dev by default, we would need to either

• Remove the go.mod file (not preferred)
• Publish a new tag < v2.0.0, or
• Change the module name from
  

  trafficcontrol/go.mod

  Line 1 in fe6f36b

  module github.com/apache/trafficcontrol

  
  to github.com/apache/trafficcontrol/v6 and release a new v6.x.x version

Does that sound right to you, @jba?

[jba]

Right. The simplest thing is the second option. Tag your repo v1.2.0, for instance, and we will show that version as the latest.

[ocket8888]

Could you please explain what you mean by "tag your repo"? We have a v6.0.0 tag on GitHub (I just made a "release" from it in case that matters, but the tag itself has been around for over a week now release had no effect, deleted it, but the tag remains) but our pkg.go.dev page still says our latest release is "5.1.3+incompatible".

How can we make the tag greater than version 1?

[jba]

@ocket8888, the tag must be for a v0 or v1 version. But just to be clear about what I was suggesting, I was commenting on @zrhoffman's three bullet points:

• Remove the go.mod file

Please no; this would be a regression.

• Publish a new tag < v2.0.0

This is the "second option" I referred to in my comment. The actual commands would be something like (assuming you're on master):

git tag v1.2.0
git push origin v1.2.0

Because this would be a v0/v1 version with a go.mod file, pkgsite would consider it the latest version for the module path github.com/apache/trafficcontrol.

• Change the module name to github.com/apache/trafficcontrol/v6.

This is the only way to properly have a module with major version 6; that is, to have your v6 tag recognized by pkgsite as the latest version. As the Go Module Reference states,

If the module is released at major version 2 or higher, the module path must end with a major version suffix like /v2.

[ocket8888]

If the module is released at major version 2 or higher, the module path must end with a major version suffix like /v2.

But why, though? I can do go mod edit -require github.com/wilk/[email protected], but I can never do go mod edit -require github.com/wilk/[email protected]? My go.mod file lists versions down to the commit hash for my dependencies, so why do they also need to be specified in the module path - but only sometimes? That doesn't even really seem like versioning the package at all, it's just releasing a different package with a similar name and something that looks like - but by no means must be - a version number in it. I don't like living in a world where go mod edit -require github.com/wilk/uuid/[email protected] is a sensible command.

It's looking like our three options are all undesirable, and currently zrhoffman is working on a solution (#6305) where we just have to make 5000 2500 lines of changes to replace the module name everywhere it's imported - but packages don't list themselves as dependencies, they compile the source as-is, so our own source shouldn't have to care about its own version at the import path level, external tools already have a way to specify versions, so I'm just struggling to understand why putting a version in the module path is necessary (design-wise; technical-wise its necessary because that's how the tooling works which I get)

[jba]

The short answer is that a new major version involves a breaking change, and breaking changes should never actually break existing users, and so require a different module path. You don't have to move to v2 and add /v2 to your path—you could also just pick a different path entirely, as when the protobuf folks moved from github.com/golang/protobuf to google.golang.org/protobuf—but keeping a similar name has obvious advantages.

But you are not alone. For more (much more than you probably want), see https://golang.org/issue/44550.

[zrhoffman]

That doesn't even really seem like versioning the package at all, it's just releasing a different package with a similar name and something that looks like - but by no means must be - a version number in it. I don't like living in a world where go mod edit -require github.com/wilk/uuid/[email protected] is a sensible command.

There is no such thing as github.com/wilk/uuid/[email protected]. If you include /v3, it will only grab version greater than or equal to v3 and less than v4. As @jba says, the idea is that, once you require a module like github.com/go-acme/lego/v3, you

• don't need to specify an exact version in order to grab v3, and
• can can upgrade to the latest version of that package without importing breaking changes (presumably in v4 and above).

[ocket8888]

Well that's good to hear, at least there's no v3@2 stuff going on

[zrhoffman]

One thing to note is that, although appending /v6 to the module path would make the new module path importable, the latest Go docs would not replace the v5.1.3+incompatible Go docs.

To see this effect on another project, although Migrate's readme says, for v3

DO NOT USE - No longer supported

The pkg.go.dev documentation for go-migrate shows v3

with v4 at, as expected, a separate path:

So, getting the newer version to show up on pkg.go.dev will not keep the older version from showing up on pkg.go.dev by default at the repo's path.

[jba]

You could deprecate it (in which case we'd show a banner) or you could retract all versions (in which case we wouldn't show it). https://go.dev/about#removing-a-package.

[ocket8888]

In the discussion to which jba kindly linked us, a proposal is linked for automating the package path updating associated with major version revs: golang/go#32014. It's not done yet, but could possibly help. I still think 2500 lines of changes for simple version housekeeping on every release is far, far too much, and I'm not so much concerned with using my editor's find/replace function as I am with having to comb through those changes and ensure they were all intentional. Nevertheless, that tool would be an improvement over a manual update, and probably much less error-prone (although documentation e.g. in READMEs and comments would have to be done by hand, still, in all likelihood). Also we'd have cool imports like github.com/apache/trafficcontrol/traffic_ops/v4-client/[email protected] which has a confusing number of embedded versions. Though it may be literally simple to know which version means what, that's still confusing for a human to look at.