theme: prefix git tags with 'v' to support go module versioning

[tlindsay42]

Noticed that release tags currently don't include the v prefix required in the go module version spec, so customers using this theme via hugo modules currently use the fallback of the pseudo-version (v0.0.0-{commit timestamp}-{commit hash}). This makes it slightly more difficult for customers to determine what version they're using.

I created a fork and cut a release to illustrate the difference.

Here's what Relearn 5.12.5 looks like in a customer's go.mod and go.sum when added via hugo mod get github.com/McShelby/[email protected]:

go.mod

...
require (
	github.com/McShelby/hugo-theme-relearn v0.0.0-20230328175520-a3ea10c374cb // indirect
)

go.sum

github.com/McShelby/hugo-theme-relearn v0.0.0-20230328175520-a3ea10c374cb h1:Ab7GfqjEq4VrhyjwYO1QeQAGnaGwBu4KSYclCSVsVhQ=
github.com/McShelby/hugo-theme-relearn v0.0.0-20230328175520-a3ea10c374cb/go.mod h1:mKQQdxZNIlLvAj8X3tMq+RzntIJSr9z7XdzuMomt0IM=

And here's what Relearn 5.12.5 looks like in a customer's go.mod and go.sum files when added via hugo mod get github.com/tlindsay42/hugo-theme-relearn/[email protected], which is more straightforward for customers.

go.mod

...
require (
	github.com/tlindsay42/hugo-theme-relearn/v5 v5.12.5 // indirect
)

go.sum

github.com/tlindsay42/hugo-theme-relearn/v5 v5.12.5 h1:iQRRTkBg4lmBM1Qh3YqY6L0HrXfC5ZwDLK/gkT1YJyo=
github.com/tlindsay42/hugo-theme-relearn/v5 v5.12.5/go.mod h1:GlB5FATi/W/eSPtWoW53pAD6uMp82u2NTyOq78w/49Y=

To implement this successfully, you'll also need to append the current major version to your module statement in go.mod L1, and bump it as part of the workflow for major version changes.

- module github.com/McShelby/hugo-theme-relearn
+ module github.com/McShelby/hugo-theme-relearn/v5

If you choose to proceed, it's probably worth adding a note and/or example to the installation section to help out customers unfamiliar with go modules, as neither Hugo, nor Golang, do a great job of explaining how this works in an easily approachable manner (especially for major versions above v1).

Example:

1. Customers should run the following to add the module

   hugo mod get github.com/McShelby/hugo-theme-relearn/[email protected]

2. Add the theme to the config

   theme = ['github.com/McShelby/hugo-theme-relearn/v5']

3. And add the module import statement to the config

   [[module.imports]]
   path = 'github.com/McShelby/hugo-theme-relearn/v5'

[McShelby]

I can not promising anything, yet.

Personally I dislike the arbitrary v prefix but have to further investigate if that change is reasonable.

Also, it's unclear how to proceed with the existing tags. And what to do with the current tag x for the latest version.

[tlindsay42]

Cool np. I personally hate the v prefix too, but that's Golang's spec. Just wanted to make you aware of the current CX and provide data to make an educated decision.

My recommendation for the existing tags is to not do anything. Leave the old release tags as-is as it's unlikely that new customers are going to pin to old versions. For the v tags to work on older versions, you'd have to rewrite your commit history to add the major version suffix to the go.mod file for versions 2-5, which would be a breaking change for existing customers using the existing pseudo-versioned releases via hugo modules.

If you choose to adopt this, the upgrade would require existing customers to update their import and theme path to add the major version suffix, so my recommendation is to start this as a new major version release: v6 and add documentation to help customers upgrade.

Not a huge issue by any means and not all major hugo theme providers are doing this. Just an observation with potential to improve ongoing CX.

[tlindsay42]

Also, I'm willing to send over a PR for this.

[McShelby]

Thanks ❤️ for the advises.

I'll first have to decide which way to go. If I then need further help, I'll post to this issue.

[McShelby]

@tlindsay42 I am willing to do this for an upcoming v6 and it shouldn't be complicated as the current GitHub actions are already modifying files during the release.

Anyways, with this kind of versioning what's the command to always use the latest version - regardless of a major version change and also, what's the command to stay on a minor release but getting all patch release versions?

At the moment I am providing tags for this. Eg. the version 5.12.6 is tagged alike plus also having the tags 5.12.x, 5.x and x. Will this still be necessary with the v format tags?

[tlindsay42]

@tlindsay42 I am willing to do this for an upcoming v6 and it shouldn't be complicated as the current GitHub actions are already modifying files during the release.

Sounds good & agreed.

Anyways, with this kind of versioning what's the command to always use the latest version - regardless of a major version change and ...

If you proceed, this project will inherit golang's minimal version selection philosophy, which means that major version changes require explicit changes by the customer. To perform a major version upgrade, they'll have to do 3 things:

1. Run the following to update the theme's go module (reference):

   1. Specific version (recommended):

      hugo mod get github.com/McShelby/hugo-theme-relearn/[email protected]

   2. Latest in major version:

      hugo mod get github.com/McShelby/hugo-theme-relearn/v6

2. Update the theme's major version in the config file:

   - theme = ['github.com/McShelby/hugo-theme-relearn']
   + theme = ['github.com/McShelby/hugo-theme-relearn/v6']

3. And update the module import statement:

   [[module.imports]]
   - path = 'github.com/McShelby/hugo-theme-relearn'
   + path = 'github.com/McShelby/hugo-theme-relearn/v6'

...also, what's the command to stay on a minor release but getting all patch release versions?

Golang doesn't offer a version constraint mechanism for accomplishing this unlike pretty much every other major package management system. It's baffling and I hate it, but that's what they decided on and is what it is.

At the moment I am providing tags for this. Eg. the version 5.12.6 is tagged alike plus also having the tags 5.12.x, 5.x and x. Will this still be necessary with the v format tags?

Nah, but it shouldn't impact your customers much because customers that consume your theme via hugo modules are still ultimately pinned to commits despite the tag via the go module fallback of pseudo-versioning. Same for any customers that consume your theme via submodule, as git submodules are also pinned to commits and (still) has no interop with git tags. Even more so for anyone that consumes your theme via download.

IMO, hugo modules are the best of the 3 (for both customers and theme providers), but given the poor documentation and unintuitive aspects around these, I recommend adding some documentation to help out your customers.

[McShelby]

During the last year, I've changed my mind a bit about this.

While in general, go versioning sounds like a preferable goal, I am reluctant of implementing it due to the fact that the build of Hugo's theme repository is quite brittle if theme authors are switching major verion numbers.

This might be due to the fact that they are unexperienced in go versioning - but so am I.

It's not off the table, but will not happen in my foreseeable future.