Go module version tags should be prefixed with subdirectory

[bkrl]

When a Go module is in a subdirectory of the Git repository, the version tags should be prefixed with the subdirectory. Here's the relevant paragraph from the Go docs:

If a module is defined in a subdirectory within the repository, that is, the module subdirectory portion of the module path is not empty, then each tag name must be prefixed with the module subdirectory, followed by a slash. For example, the module golang.org/x/tools/gopls is defined in the gopls subdirectory of the repository with root path golang.org/x/tools. The version v0.4.0 of that module must have the tag named gopls/v0.4.0 in that repository.

Our main module is in the wowchemy subdirectory but the version tags aren't prefixed with wowchemy/, so Go does not recognize them. For example, doing hugo mod get github.com/wowchemy/wowchemy-hugo-modules/wowchemy/[email protected] results in the error message go: github.com/wowchemy/wowchemy-hugo-modules/wowchemy/[email protected]: invalid version: unknown revision wowchemy/v5.5.0, indicating that Go can't find the wowchemy/v5.5.0 tag. This means that the latest commit will be used by default instead of the latest version, so users will end up between versions which makes updates harder.

Putting the module at the root of the repository (github.com/wowchemy/wowchemy-hugo-modules) in go.mod doesn't help because its go.mod file specifies an old version of the github.com/wowchemy/wowchemy-hugo-modules/wowchemy module. It would also get automatically removed by hugo mod tidy since the config file imports the module in the subdirectory instead of the module at the root of the repository.

If we add tags prefixed with wowchemy/ and wowchemy-cms/ for each version, Go should automatically put the latest version in go.mod instead of a pseudo-version for the latest commit when updating or using hugo mod tidy. The go.mod file at the root of the repository shouldn't be necessary anymore.

[gcushen]

Thanks for the feedback!

Most users and contributors are academics and aren't very familiar with Go or Go Modules. Originally, we had a simple system that both maintainers and users found easy to understand.

We originally versioned the whole repo with a single tag and users could simply require one root repo module (this file still exists, although no longer works due to changed behaviour in Hugo/Go) at a specific version and know that all the modules they are using are compatible.

However, the newer version of Go Modules that recent Hugo versions use no longer support this behaviour - it's no longer possible to use replace in a go.mod that is not root (i.e. now replace can only be used in the user's site go.mod).

Users can still upgrade to specific versions using the commit associated with each release rather the version tag directly: https://wowchemy.com/docs/hugo-tutorials/update/#tldr

We are considering versioning each module independently, however it may introduce more complexity for less-technical users such as in terms of compatibly of modules with different version tags, and in terms of updating with more noisy release notes rather than one linear, unified release notes page on GitHub.

There's also the question of how we handle previous tags. Do we retrospectively develop a script to convert all previous tags (both pre and post the date Hugo supported Go Modules) to use the Go subdirectory tag naming convention? How would we perform this without loosing all the previous GitHub release notes?

Also, there is currently only one regular maintainer on this repo. Unless, more members of the community are willing to regularly get involved in the maintenance of the repository, it may be hard to prioritise spending time on an individual release process for each module over all the existing requests which have more upvotes from users.

On a side note, it might be nice to further organise the repo, breaking it down more granularly into both Go modules and Go packages, however Hugo doesn't currently support the concept of organising things more granularly with Go Packages. @bkrl if you have any ideas around further breaking down and organising the repo, such as into more modules, feel feel to add your comments!

[bkrl]

I think we can just add tags with the subdirectory prefixes in addition to the existing tags. For example, for v5.5.0, you would add wowchemy/v5.5.0 and wowchemy-cms/v5.5.0 tags that point to the same commit as the existing v5.5.0 tag. That should make Go recognize them without needing any significant or breaking changes.

[gcushen]

@bkrl thanks for the really helpful comments! Based on your feedback, I have made a few improvements:

Organised modules in a new modules folder: https://github.com/wowchemy/wowchemy-hugo-themes/tree/main/modules

Split out Netlify support as a dedicated module so that users deploying to other hosts can exclude the Netlify files: https://github.com/wowchemy/wowchemy-hugo-themes/tree/main/modules/wowchemy-plugin-netlify

New module paths:

module:
  imports:
    - path: github.com/wowchemy/wowchemy-hugo-themes/modules/wowchemy-plugin-netlify-cms
    - path: github.com/wowchemy/wowchemy-hugo-themes/modules/wowchemy-plugin-netlify
    - path: github.com/wowchemy/wowchemy-hugo-themes/modules/wowchemy/v5

Docs on updating: https://wowchemy.com/docs/hugo-tutorials/update/#tldr

Will plan to reference the above in the release notes for v5.6.0.

[bkrl]

Thank you so much for your work on this project!