Inconsistent and vague docu on minimum required hugo version

[deining]

I just skimmed through our sites, looking for minimum required hugo version. That's what I found:

README.md, section prerequisites: we recommend version 0.53 or later theme.toml: min_version = 0.53

• Userguide:
  • section deployment: Specify HUGO_VERSION as the Key for the new variable, and 0.53 or later as its Value.
  • section Getting started, v 0.1.0: we recommend version 0.75.0 or later
  • section Getting started, HEAD: must be version 0.77.0 or later (this edit was done by me in the course of changing docsy to a module, this edit was a bit hasty and therefore premature, sorry).

I have two problems with that:

• declared miniumum required version should be consistent all over the place
• something like we recommend hugo version x.xx.x seem too vague to me. What meaning does that convey to the user? We don't really know by ourselves, so you may be able to keep your old, outdated version, good luck!

What was the reason of recommending 0.75.0 or later? Can anyone shed some light on this? Thanks.

[chalin]

Thanks for the detailed analysis. We should definitely clean that up.

Given the limited development resources that Docsy has, I'd suggest that we officially support only the release of Hugo specified in package.json (which we'll be keeping up to date):

https://github.com/google/docsy/blob/19e0072b55bd42cdf4e9e58008147d604e3d31b4/package.json#L12

Go gRPC, does something similar but with a version window of three:

Prerequisites

• Go, any one of the three latest major releases of Go.

The three latest major releases of Go are currently, 1.15, 1.16, 1.17.

We don't have the equivalent of Google's gRPC-Go development team, so I'd recommend that we officially support a single Hugo version.

@LisaFC @emckean, thoughts?

[deining]

Given the limited development resources that Docsy has, I'd suggest that we officially support only the release of Hugo specified in package.json (which we'll be keeping up to date):

You are addressing the issue of the officially supported version, while I was talking about minimum required version. Both are different concepts, IMHO, in that sense:

• officially supported version: this is the only supported version, if you use any other version and run into trouble, you are at your own.

• minimum required version: we know for sure, that docsy breaks with version x.x.x, don't even try it, it's a waste of time.

• IMHO, we should tell a minimum required version of docsy, at least if we are aware of anys issue inside docsy with versions older than x.x.x Or can we force everyone onto the lastest released version (0.92.0)? I don't think so.

  In order to find out hugo versions used out in the field, I started issue new thread inside our discussion forum.

Recommendation for 0.75.0 or later

I just found this issue in the example-site repo which explains the motivation behind this:

0.75.0 is the minimum version for the print feature to work so I'll update the docs.

However, print feature was amended by this commit( https://github.com/google/docsy/commit/2c411821dbd206821fb586f6ab75cae1302c1f99), so even versions below 0.75 should be fine right now.

[chalin]

Right, I understand your concern, but any concept that the docsy team documents has a maintenance cost. If we document a min version of Hugo, we need to validate that claim and maintain it over time. IMHO, we have other more pressing concerns & features to spend our time on.

With Google's engineering budget for gRPC-Go their min version is only two steps away from the latest release of Go. With our budget of 0, I think it's ok to only officially support a single version of Hugo (and let the community handle discussions about possible min versions, on a best effort basis). That's my 2 cents.

[LisaFC]

@emckean, @geriom, what do you think?

I do think "minimum required" is potentially useful information, otherwise we're essentially telling all users to upgrade/downgrade to the same version of Hugo or unspecified wrongness could happen ranging from "this one small feature won't work" to "your site will not build". I don't know how onerous most users will find upgrading, or how much work it would be to document when we make a change dependent on a version of Hugo - it's not like we have an elaborate test suite even for our current version right now....

We could also strongly recommend that users use our current Hugo version.

There's also the scenario where Hugo update and it breaks Docsy (as has happened when they eg changed the default Markdown parser), though in that case I think it's a fairly clear "we should fix Docsy and specify how to upgrade".

[emckean]

I like 'officially supported' and, if we have time as we build out the tests, we can see which Hugo versions 'work' and make that info available?

[chalin]

The decision made at the 2022/01/31 PSC meeting was to pull any mention of a minimum Hugo version from the docs. Of course, we'll support and encourage the community's best-effort input on what it believes the currently usable min Hugo version might be. (Note that some PSC members have followup action items related to this.) Does that sound about right @LisaFC @emckean @geriom?