Improve deprecation error message

[xuhdev]

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 adityatelange/hugo-PaperMod#1573 (comment), .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:

• 6 releases of INFO: v0.124.0 - v0.129.0
• 6 releases of WARNING: v0.130.0 - v0.135.0
• Then ERROR: v0.136.0 onward

[jmooring]

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]

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]

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]

@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]

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]

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

[olib14]

My own confusion with this stems from my build being blocked, but looking at the version number and seeing the feature has not yet been removed.

It would be, in my opinion, better to simply remove the feature and then (and thereafter) throw the error that the feature was removed in version x. Throwing a blocking error whilst the feature still exists in the code is bizarre — it's not something I think anyone would expect.

[bep]

I'm closing this, this works as designed.

[github-actions]

This issue has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.