Deprecation of functions, methods, etc

[jmooring]

Last updated: 2023-11-10T21:43:07-08:00

This information is now included in the Hugo documentation.

---

When a project deprecates something, they are telling its users:

1. Don’t use Thing One anymore
2. Use Thing Two instead
3. We’re going to remove^[1] Thing One at some point in the future

Think of deprecation as a statement of intent.

With previous releases, Hugo’s deprecation notices were somewhat abrupt. Upon upgrading to a version with a new deprecation, Hugo would immediately emit warning messages to the console when building the site, and the duration between deprecation and removal was unclear.

The deprecation/removal behavior with v0.120.2 and later is formalized and more friendly. After something has been deprecated in code, Hugo will:

1. Log an INFO message for 6 minor releases^[2]
2. Log a WARN message for another 6 minor releases
3. Log an ERROR message and fail the build thereafter

To see the INFO messages, you must use the --logLevel command line flag:

hugo --logLevel info

To limit the output to deprecation notices:

hugo --logLevel info | grep deprecate

Run the above command every time you upgrade Hugo.

---

1. Also referred to as “sunset” ↩︎

2. For example, v0.1.1 => v0.2.0 is a minor release ↩︎