feat: 'optional_updated' option

[curbengh]

What does it do?

Continuation of #3235, specifically #3235 (comment).

User may prefer to have full control on value of post.updated and not use file modification time. Currently for my blog, I have to use a new variable lastUpdated as a workaround; since that variable is not recognized by many plugins, I have to fork many plugins.

With this PR, config.optional_updated can be enabled (disabled by default), to leave post.updated to be empty if updated: is not set in the front-matter.

Breaking changes

Post and Page model no longer assign default moment() value to updated property.

• This can break plugin's and theme's unit test, regardless of optional_updated (because the option is not passed to the model), assuming all the following conditions exist:
  1. Uses Post/Page model (example)
  2. Uses post.updated/page.updated variable (example)
  3. Doesn't perform null-checking on post.updated/page.updated.
• Outside of unit test (or in real world), this only break plugin and theme if optional_updated is enabled, assuming all the following conditions exist:
  1. Uses post.updated/page.updated variable
  2. Doesn't perform null-checking on post.updated/page.updated. (e.g. hexo-theme-next doesn't check)

How to test

git clone -b custom-updated https://github.com/curbengh/hexo.git
cd hexo
npm install
npm test

Screenshots

Pull request tasks

• Add test cases for the changes.
• Passed the CI test.

[coveralls]

Coverage increased (+0.003%) to 97.125% when pulling 26133ca on curbengh:custom-updated into 6216d05 on hexojs:master.

[curbengh]

@tomap Relating to the issues addressed by #3235, I prefer the approach of leaving post.updated to be empty.

The main reason is that it's easier for theme/plugin to handle, e.g.

if (post.updated && post.updated.toString() !== post.date.toString()) { %>

can be simplified to

if (post.updated) { %>

[curbengh]

This is necessary to allow page.updated to be null.

[curbengh]

In actual use, data.updated won't be null (if optional_updated is disabled, which is the default), thanks to

hexo/lib/plugins/processor/post.js

Line 90 in 2146a03

data.updated = stats.mtime;

.

[curbengh]

Enabling this config will break themes/plugins that assume post.updated won't be null, especially the one which uses hexo as API in their unit test.

So far, I notice hexo-generator-sitemap is compatible, but not hexo-generator-feed.

---

I also tried to minimize the breaking change by retaining this line, then set data.updated to empty string. But moment model doesn't like empty string.

[curbengh]

I'm not very keen optional_updated naming, I initially used strict_updated. Any suggestion welcomed.

[SukkaW]

If the Breaking Changes is inevitable, then we might move it to Hexo 5.0.0.

Also an idea is to merge config.use_date_for_updated and config.optional_updated into config.updated_option. We could have options like mtime, date, empty.

[curbengh]

If the Breaking Changes is inevitable, then we might move it to Hexo 5.0.0.

Added to v5 milestone

Also an idea is to merge config.use_date_for_updated and config.optional_updated into config.updated_option. We could have options like mtime, date, empty.

+1, I'll create config.updated_option in a separate PR.

[curbengh]

Superseded by #4278.