search

gohugoio / hugo

The world’s fastest framework for building websites.
https://gohugo.io
Apache License 2.0
75.76k stars 7.53k forks source link

Improve deprecation error message #12949

Open xuhdev opened 3 weeks ago

xuhdev commented 3 weeks ago

What version of Hugo are you using (hugo version)?

$ hugo version
hugo v0.136.0-2939270a3bb78b3799973345c0dab7fa239cef9d+extended linux/amd64 BuildDate=2024-10-15T13:17:24Z VendorInfo=gohugoio

Does this issue reproduce with the latest release?

Yes.

According to https://github.com/adityatelange/hugo-PaperMod/issues/1573#issuecomment-2415547309, .Site.Social is removed in v0.136.0. However, I'm getting the following error message:

ERROR deprecated: .Site.Social was deprecated in Hugo v0.124.0 and will be removed in Hugo 0.137.0....

Note the version says 0.137.0, while the error producing release is v0.136.0. This version mismatch seems to be happening for other deprecated features I encountered in the past.

Based on the deprecation policy, it seems the string should be "...removed in Hugo 0.136.0". The following is the math:

jmooring commented 3 weeks ago

The existing message is about when the feature will be removed from the code base, not when it will stop working.

Once we start throwing the error (i.e., when the feature stops working), the date that we say we will remove the feature will always be the current version + one minor release... so that number will continue to increase by one until we remove the feature from the code base. In reality we will leave the deprecated feature in the code for at least 6 minor releases after we start throwing an error.

xuhdev commented 3 weeks ago

Thanks for the clarification. However, the user probably doesn't really care when the actual code is removed, so this string is a bit confusing. Plus, as you suggested, the information isn't quite correct anyway... So, perhaps at least a better wording?

jmooring commented 3 weeks ago

the user probably doesn't really care when the actual code is removed

That's debatable. Maybe we could change the ERROR message to:

.Site.Social was deprecated in Hugo v0.124.0.

ferdnyc commented 3 weeks ago

@jmooring

That's debatable. Maybe we could change the ERROR message to:

.Site.Social was deprecated in Hugo v0.124.0.

That's one option. Though, users probably care less about when the feature was deprecated, as when they'll no longer be able to use it. (Also mentioning how long ago it was deprecated can help fend off cries of "surprise" removals, though.)

Ideally INFO/WARNING messages would be used to inform the user of exactly what point (in terms of Hugo version numbers) a feature will start breaking their code. From the very first INFO message, the most important piece of information (only important information, really) from a user perspective is, .Site.Social will TRIGGER BUILD ERRORS AND BREAK YOUR SITE starting with Hugo v0.136.0. Everything else is irrelevant.

If knowing when the deprecation started makes it easy to figure that out (if it's always + 12 minor versions), then great! Hugo can just do that math instead of making users figure it out, and display .Site.Social {will be,was} disabled in v0.136.0 rather than anything involving either v0.124.0 or the kick-the-can-down-the-road "current version + 1 minor version". (Or, like I said, it can show both: .Site.Social (deprecated since Hugo v0.124.0) {will be,was} disabled in v0.136.0.)

(As an aside, "DEPRECATED ERROR" is also a weird label — an API being "deprecated" means it's still usable, but is slated for future removal and not recommended for use. It should be avoided in new code, and migrated away from in old code. Failing with an ERROR when the API is accessed usually comes after the deprecation period has ended, and represents the transition to the next phase after deprecation — "disablement", for lack of a better word.)

jamesanderson9182 commented 2 weeks ago

Is there a temporary work around for this error? Running hugo server doesn't work for me at all (I'm just getting started).

jmooring commented 2 weeks ago

@jamesanderson9182 Please ask your question in the forum (https://discourse.gohugo.io/). The answer will depend on the theme. Thanks.