How to fix go release versioning on Github that has backward tag version?

Question

I have a go module release to Github. At the beginning, I tagged it to v1.0.0 it was running perfectly on my main program importing that module directly from Github.

But on the next release, I've tagged it backward to v.0.1.1 because I think my module is not stable yet -> (based on semantic versioning unstable version must begin with 0.x.y).

This makes an issue today because I use golint and this tool, it says go-mod-outdated. Currently, the version is v0.5.x and there is a lot of release before it (before I use lint and some tool for lint)

Any ideas to fix it?

Answer 1

Semver side of things

According to semver, unstable more recent versions can be marked as such with a hyphen, as per spec item 9

A pre-release version MAY be denoted by appending a hyphen and a series of dot separated identifiers immediately following the patch version. Identifiers MUST comprise only ASCII alphanumerics and hyphens [0-9A-Za-z-]. Identifiers MUST NOT be empty. Numeric identifiers MUST NOT include leading zeroes. Pre-release versions have a lower precedence than the associated normal version. A pre-release version indicates that the version is unstable and might not satisfy the intended compatibility requirements as denoted by its associated normal version. Examples: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92, 1.0.0-x-y-z.–.

So the question here is what have you changed? If you've just added some features, but not introduced any breaking changes to the API, you should tag the unstable release as: v1.1.0-alpha.1. Fixes to the unstable release can then be tagged as v1.1.0-alpha.2 and so on.

If you've changed the API of your package in a breaking way, the release should be tagged as v2.0.0-alpha.1. Fixes to the alpha should be tagged in the same way as before: increasing the last digit after the -alpha suffix.

Lastly, if you've not changed the API in any way, nor added any features, then you just tag your version as being v1.0.1-alpha. Basically, standard semver stuff.
Of course, if you're in this particular situation, then the truth is you've prematurely tagged your package as v1.0.0 prematurely, as pushing patches is still causing instability.

You can address/retag the existing v1.0.0 version by removing the tag, and tag that version accordingly. This can be easily done using the following commands:

# check out the version to re-tag
$ git checkout v1.0.0
# tag the version with the desired tag
$ git tag v0.1.1
# push the tag
# if you're brave, you could just git push --tags, but that's not ideal
$ git push origin v0.1.1
# now delete the offending tag
$ git tag -d v1.0.0
# remove the tag remotely
$ git push origin :refs/tags/v1.0.0

OK, the github repository no longer has the v1.0.0 tag. Any clone of the repository might still have the old tag, and if anyone there pushes git push --tags, that'll restore the v1.0.0 tag (hence my comment saying git push --tags is not ideal). If your package is being used in the wild, this requires some communication with all of the users of the package.

Lastly, moving forwards, you'd do well reading up on how go mod handles versions (the gist of it is: follow semver 2.0 and you should be fine). pseudo-releases and pre-releases have a particular format you should use

Golang (go mod) specifics

Once a module is tagged and released, it's out there. What you should do is issue a retraction of a broken version using the retract directive

As @bcmills kindly pointed out in the comments: the retract directive only works for later versions. The solution for your particular case (actually being on version v0.5.x, but wanting to retract release v1.0.0) can be done by tagging a later version and retracting it:

retract (
    v1.0.0
    v1.0.1 // the new version that issues the retraction retracts itself
)

From this point on, the latest version of your package that hasn't been retracted would be v0.5.x, and you should be all set.

To issue the retraction of your optimistically tagged release. If you've re-tagged this release as being, for example, v0.1.0, then you may be able to use the replace directive. I'll be honest, I've never used replace to point one version of my module to another version of the same module, but it's might be worth a shot:

replace (
    github.com/your/package v1.0.0 => github.com/your/package v0.1.0
)

I must say: even if this works, it's a hack, and I can't vouch for it playing nice with new versions of your package being released. I'd strongly recommend you to issue a retraction of the v1.0.0 tag, re-tag it (arguably v0.0.0 is the version to use here), and from this point on, follow the semver and golang pre-release/pseudo-release versioning standards.