Closed bkrl closed 2 years ago
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!
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.
@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.
Thank you so much for your work on this project!
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:
Our main module is in the
wowchemy
subdirectory but the version tags aren't prefixed withwowchemy/
, so Go does not recognize them. For example, doinghugo mod get github.com/wowchemy/wowchemy-hugo-modules/wowchemy/v5@v5.5.0
results in the error messagego: github.com/wowchemy/wowchemy-hugo-modules/wowchemy/v5@v5.5.0: invalid version: unknown revision wowchemy/v5.5.0
, indicating that Go can't find thewowchemy/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
) ingo.mod
doesn't help because itsgo.mod
file specifies an old version of thegithub.com/wowchemy/wowchemy-hugo-modules/wowchemy
module. It would also get automatically removed byhugo 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/
andwowchemy-cms/
for each version, Go should automatically put the latest version ingo.mod
instead of a pseudo-version for the latest commit when updating or usinghugo mod tidy
. Thego.mod
file at the root of the repository shouldn't be necessary anymore.