Publish markdown files to readme.com with updatedAt values based on the git timestamps

[chrisjrn]

Currently, updating updatedAt values is a manual task, often overlooked by people updating the docs. This makes the docs appear more stale than they actually are (#18436).

With adhoc_tool support, it should be possible to create a Pants-managed workflow to publish docs to readme.com.

We should be able to write a tool to update the front matter of the docs to have a correct updatedAt value based on the mtime of the files, and then publish the post-processed files using the rdme node.js-based tool.

[benjyw]

The git timestamps are a more accurate representation of the creation/update times that the mtimes. For example, when cloning a repo all the mtimes will be now-ish.

[jsirois]

Assuming readme.com is not lying here, they dogfood a GitHub action - no Pants tooling required: https://docs.readme.com/main/docs/rdme

I'd hope their dogfood includes bumping updated at, but it seems easy enough to find out.

[benjyw]

I looked at that action and as far as I can tell it just installs and runs the rdme client for you, and does no updating of updatedAt.

[benjyw]

Oh, but, can also confirm that the rdme client does the right thing on upload. The change isn't reflected in the source of course, but it looks like it is on the server:

(I synced the file 15 minutes ago, but its updatedAt in the source is older)

[benjyw]

Can also confirm that this all still works if we delete updatedAt entirely. So I will do that.

[benjyw]

OK, it's a little more complicated than that. If updatedAt exists, it is used to set that user-visible "last updated" text.

If it doesn't exist, the current time at sync is used, but only if the body has changed (changing the front matter doesn't affect the updated time, even though it will cause rdme to sync the file). So simply deleting updatedAt will freeze the user-visible last updated time at whatever it was in the file before we deleted it, until that file's body is next updated.

So what we actually want to do to get correct user-visible last updated times is to set the updatedAt time based on the most recent git timestamp, sync, and then delete the field.

[benjyw]

#18475

(I temporarily set the updatedAt time for that one-time sync, and synced to 2.16.x, so there is no need to check that in).

[cburroughs]

Is this still relevant with the new docs site?

[benjyw]

Is this still relevant with the new docs site?

Nope, I'll close this. Thanks!