Use Go/Hugo-friendly git tags

[WhiteEyeDoll]

Hugo mod requires that tags follow the semver pattern vMAJOR.MINOR.PATCH.

The latest tag 0.2.0-pre with the deletion of v0.2.0-pre breaks module functionality. Tag 0.2.0-pre is not seen as a proper version for a go module as the "v" prefix is required.

https://go.dev/blog/publishing-go-modules

[WhiteEyeDoll]

Also deleting/overriding tags released to public is not considered best practice for git. Tagging pre release versions as v0.2.0-alpha1, v0.2.0-alpha2 and so on would be beneficial.

[chalin]

Thanks for the feedback @WhiteEyeDoll.

/cc @deining - re. the Hugo module version ID requirements (not my area of expertise so I'll let Andreas comment).

Btw, we'll eventually follow semver, but we aren't at the moment. Thanks for your patience as we make it through this initial turbulence to our first official release.

[chalin]

Hugo mod requires that tags follow the semver pattern vMAJOR.MINOR.PATCH.

As you probably know, semver doesn't mandate a v prefix. Can you provide a link to the Hugo docs that says that Hugo module IDs must have the pattern that you've named?

[WhiteEyeDoll]

Could it be possible to push a working tag to mitigate this? I'm developing multiple new pipelines that use the hugo mod functionality and could provide feedback regarding this.

[WhiteEyeDoll]

Hugo modules are go modules and those require the "v" prefix.

https://go.dev/ref/mod#versions

Versions
A version identifies an immutable snapshot of a module, which may be either a release or a pre-release. Each version starts with the letter v, followed by a semantic version. See Semantic Versioning 2.0.0 for details on how versions are formatted, interpreted, and compared.

https://go.dev/blog/publishing-go-modules

Semantic versions and modules
Every required module in a go.mod has a semantic version, the minimum version of that dependency to use to build the module.
A semantic version has the form vMAJOR.MINOR.PATCH.

https://gohugo.io/hugo-modules/

Hugo Modules are powered by Go Modules. For more information about Go Modules, see:
https://github.com/golang/go/wiki/Modules
https://blog.golang.org/using-go-modules

[WhiteEyeDoll]

https://go.dev/doc/modules/version-numbers

[chalin]

Could it be possible to push a working tag to mitigate this?

Done! Apologies for the breakage.

[chalin]

FYI: https://semver.org/#is-v123-a-semantic-version

I'll still want to discuss this with @deining, and will get back to you after.

[WhiteEyeDoll]

Thanks for the fast response. This fixed the issue.
Required updating the checksum as the tag content had changed but pipelines are now healthy. 👌

❯ hugo mod get -u
go mod download: github.com/google/docsy@v0.2.0-pre: invalid version: resolves to version v0.2.0-pre.0.20220321183617-02df04c0f2d4 (v0.2.0-pre is not a tag)
hugo: collected modules in 859 ms
go: downloading github.com/google/docsy v0.2.0-pre
verifying github.com/google/docsy@v0.2.0-pre: checksum mismatch
downloaded: h1:6wMuNykLOXWksEP8aRuTYXNxKCvjr35cZb/kX1KXHBE=
go.sum: h1:vQc8vUD6ArSKCZM2BA1tckwhHSA5Vi3GwqtdywQiAaU=
SECURITY ERROR
This download does NOT match an earlier download recorded in go.sum.
The bits may have been replaced on the origin server, or an attacker may
have intercepted the download attempt.
For more information, see 'go help module-auth'.
go: downloading github.com/google/docsy v0.2.0-pre
verifying github.com/google/docsy@v0.2.0-pre: checksum mismatch
downloaded: h1:6wMuNykLOXWksEP8aRuTYXNxKCvjr35cZb/kX1KXHBE=
go.sum: h1:vQc8vUD6ArSKCZM2BA1tckwhHSA5Vi3GwqtdywQiAaU=
SECURITY ERROR
This download does NOT match an earlier download recorded in go.sum.
The bits may have been replaced on the origin server, or an attacker may
have intercepted the download attempt.
For more information, see 'go help module-auth'.

[WhiteEyeDoll]

Yes the prefix "v" is a convention and has been a discussion point in the past regarding go modules.

golang/go#30146

[chalin]

Again, @deining is the expert here, but from my investigations, I think that we've been using Pseudo-versions, and for these:

Pseudo-versions may refer to revisions for which no semantic version tags are available.

[chalin]

Thanks for all the feedback. Hopefully, we'll get all this straightened out before 0.2.0 is officially released (#955). /cc @LisaFC @emckean @geriom

[deining]

Again, @deining is the expert here

No, still learning, too 😄

#871 was merged with revison 1e5f31c., and we assigned two tags to this revision:

• v0.2.0-pre
• dependencies/v0.2.0-pre

We partially reverted this meanwhile, but in hindsight, I doubt whether this was a good desicion since, as @WhiteEyeDoll pointed out, deleting/overriding tags released to public is not considered a good practice.

How to cope with this situation now? I would propose:

• restore the two tags (v0.2.0-pre, dependencies/v0.2.0-pre) so that they point to 1e5f31c
• delete/clear all other tags assigned in the meantime (0.2.0-pre, ...)
• create two new tags (v0.2.0-pre2, dependencies/v0.2.0-pre2) pointing to 02df04c
• eventually, create two final tags (v0.2.0, dependencies/v0.2.0) pointing to xxx (not known yet)

What do you think?

[WhiteEyeDoll]

Dunno if fixing the old stuff is required but otherwise the steps are sound. 😄
Also the convention for submodule tag is correct.
https://github.com/golang/go/wiki/Modules#faqs--multi-module-repositories

I would only question using the -pre suffix over -alpha/-beta/-rc as those sort and state the status better.

[chalin]

We partially reverted this meanwhile, but in hindsight, I doubt whether this was a good desicion since, as @WhiteEyeDoll pointed out, deleting/overriding tags released to public is not considered a good practice.

Agreed.

How to cope with this situation now? I would propose:

• restore the two tags (v0.2.0-pre, dependencies/v0.2.0-pre) so that they point to 1e5f31c

Yes. Can you make this change @deining?

• delete/clear all other tags assigned in the meantime (0.2.0-pre, ...)

We just stated that we won't remove tags moving forward, so we can let those be.

• create two new tags (v0.2.0-pre2, dependencies/v0.2.0-pre2) pointing to 02df04c

I'd skip this part so as to avoid creating yet more tags, especially since first official release is "imminent".

• eventually, create two final tags (v0.2.0, dependencies/v0.2.0) pointing to xxx (not known yet)

As it seems that v prefixes are the way to go for Go/Hugo modules, then tags will have a v prefix moving forward.

[deining]

How to cope with this situation now? I would propose:

• restore the two tags (v0.2.0-pre, dependencies/v0.2.0-pre) so that they point to 1e5f31c

Yes. Can you make this change @deining?

Done.

[chalin]

With release 0.2.0 out (which uses the tag v0.2.0), I'll close this. Let us know if there are any issues @WhiteEyeDoll.

[WhiteEyeDoll]

Well the v0.2.0 worked perfectly till it was nuked again. 😅
Creating a v0.2.1 release would have been cleaner if there was issues with v0.2.0. 🤔

[jcrummy]

I had the same issue because I had downloaded locally on my computer when the old tags were active, but by the time I had it running in a pipeline there were new tags with new checksums, so the pipeline was failing.

For anyone else struggling with this, you can get the new checksums locally by running hugo mod clean --all, which will remove all of the cached modules, then run something like hugo mod verify which will fail, but will give you enough information to manually update the go.sum file with the new checksums.

As @WhiteEyeDoll said, please don't modify tags once they are public - it causes a lot of headaches. Seeing as we are still on v0, bugs are expected, so it is much better to just release a new bugfix version, ie: v0.2.1.

[chalin]

Thanks for the feedback, we're expecting to offer a smoother experience moving forward.