I’d like to bring up some concerns about the documentation for deprecated functions, methods etc.
I observed that whenever a feature/method is deprecated, it’s removed from the documentation. This can be a problem for some people.
For example, .Site.IsServer is deprecated in Hugo v0.120.0. What if someone not using v0.120.0, needs to know about .Site.IsServer ?
Instead of removing .Site.IsServer from documentation, would it be possible to relocate it to a dedicated page, perhaps docs/content/en/deprecated-hugo-features.md?
This page could serve as a list of all deprecated features, including their respective documentation.
Put simply, I believe that a dedicated page like this would effectively convey the information:
(building upon on Joe’s list)
Don’t use Thing One anymore
Use Thing Two instead
We’re going to remove Thing One at some point in the future
Thing One’s documentation (with a note that it (is/is going to be) deprecated in favor of Thing Two.
Additionally, deprecated stuffs can be denoted with a special marker just like how new features are denoted (see the screenshot below). Perhaps something along the lines of ‘Marked as deprecated in v0.120.0’ in a striking red color.
The dedicated page is unnecessary since I doubt anyone new to Hugo would be interested in knowing what old features it had in the past. Seeing the deprecation warnings in the terminal is better since I would think a majority of Hugo users use CLI anyway.
Plus with how fast Hugo features change, that would be unmaintainable in the long run.
Let’s wait and see if the recent documentation removals cause a problem. When we deprecated URL on Page in favor of RelPermalink/Permalink, I can’t recall any documentation requests for the deprecated method.
But again, let’s wait and see. I am somewhat resistant to adding a page or creating “deprecated” markers simply due to the maintenance required.
At least kind enough to attach some information on PRs or Issues on GitHub which adding breaking changes, about what is the solution or update devs need to follow. Thanks
The release notes do contain that information. The problem is that many devs with Hugo themes don’t keep up with the releases (by being busy or other reasons), unless something breaks and is reported by users.
