弃用说明

什么是弃用

当一个项目宣布某项内容「弃用」（deprecate）时，它是在告诉用户三件事：

1. 不要再使用「甲」了。
2. 请改用「乙」。
3. 我们会在将来某个时间点移除「甲」。

常见的弃用原因包括：

• 某项功能已被更强大的替代方案取代。
• 某项功能存在设计缺陷。
• 某项功能被认为是多余的，为了简化整个系统，将来会被移除。
• 软件的后续版本会有重大结构调整，导致继续支持旧功能不可能或不切实际。
• 为了统一命名或提高一致性。
• 过去只能独立使用的功能，现在与其配套功能合并。

弃用的节奏

项目团队在代码中弃用某项内容之后，Hugo 会：

1. 在 3 个次版本（minor release）中记录 INFO 级别的消息；
2. 再在 12 个次版本中记录 WARN 级别的消息；
3. 此后记录 ERROR 级别的消息，并让构建失败。

这里的次版本指版本号中第二段数字递增的发布，例如 v0.1.1 => v0.2.0 就是一个次版本。

文档的处理

项目团队会：

1. 在弃用日期当天更新文档，加入说明弃用的注记以及相关的替代方案；
2. 在 Hugo 开始记录 ERROR 消息并导致构建失败之后的 6 个或更多次版本后移除代码。到那时 Hugo 仍然会抛出错误，但错误消息中不再提到弃用；
3. 在弃用日期两年之后移除对应的文档。

因此，升级 Hugo 时看到弃用提示，最好当场处理，而不要等到功能被移除。

如何查看弃用提示

要看 INFO 级别的消息，必须使用 --logLevel 命令行标志：

hugo build --logLevel info

只想保留弃用相关的提示时，可以过滤输出：

hugo build --logLevel info | grep deprecate

如果不指定 --logLevel，默认只会显示警告与错误，弃用初期的 INFO 提示就被淹没了，因此请在每次升级 Hugo 之后运行上面的命令。日志级别的完整说明见日志，hugo build 的其他选项见命令。