build: add REPLACEME tag for version info in docs by addaleax · Pull Request #6864 · nodejs/node · GitHub

Checklist

tests and code linting passes
the commit message follows commit guidelines

Affected core subsystem(s)

build

Description of change

Add a REPLACEME tag that should be used when introducing docs for new features, so that they can be updated when releases are made. Example usage:

## process.cpuUsage([previousValue])
<!-- YAML
added: REPLACEME
-->

Ref: #6578

@bnoordhuis This is taken straight from #6578 (comment) so I’ve set the commit author to you. I guess that’s okay with you?

Add a `REPLACEME` tag that should be used when introducing docs for new features, so that they can be updated when releases are made. Ref: nodejs#6578

If you go through the trouble of filing the pull request, you can claim authorship. :-)

LGTM either way.

Credit where credit is due, I’m going to leave it like that. ;)

LGTM, should any doc be updated mentioning this?

@claudiorodriguez Hmm… got any suggestions? It might be nice to make collaborators aware of this in some way, yes.

@addaleax right now the added metadata is documented in /tools/doc/README.md so I think it would make sense to add this there. I'd also reference it in CONTRIBUTING.md. Maybe another PR after this one?

Credit where credit is due, I’m going to leave it like that. ;)

Can you leave my LGTM out in that case? Otherwise I'd show up as both author and reviewer.

@bnoordhuis Of course, yep.

@claudiorodriguez I’ve added it here… that should be okay. Still LGTY?

So, I think it was @Fishrock123 that brought it up, but we should always know that a new feature or method will be going in in the next minor right? Is this still necessary?

@evanlucas I don’t have strong feelings about it… basically, in my head it’s like this:

Pro REPLACEME:

People who create PRs don’t need to know when they will land/don’t have to update each time a new minor comes out, if the PR is a bit more long-running
Replacing REPLACEME in the docs upon release is more or less a single search+replace operation
(If it’s relevant, this approach may be easier if it comes to backported semver-minor changes)

Contra REPLACEME:

Extra work during release
Most of the time it one can make a good guess on the version in which a feature will land

You @nodejs/release people can probably assess things better and if you prefer not to do it this way, that’s perfectly fine.

There are definitely pros to this approach. My biggest concern with going this route is how do we make the update permanent? Is that something the releaser should commit and push back up? Otherwise, when we hit the next release, the REPLACEME will be incorrect.

Would it be okay to do something like this together with/in the release commit? If I’ve understood everything correctly, that one is landed both in the version-specific branch and master.

That could work. We do cherry pick the release commit from the release proposal branch back to master. So this will probably work fine for v6, but may become a little hairy for v4. I'm honestly not sure. I do think I'm +1 on this, but really think that all of @nodejs/release should see this before landing. Also, if we add this, we need to make sure that the doc/releases.md document is updated to reflect the process of updating these.

Yeah, there’s no hurry to implement this process in any case.

And regarding v4.x in general, so far this feature isn’t even implemented there, but I think I’ll do a backporting PR once we’re pretty much through with #6578.

@addaleax yep, LGTM on the PR itself. Agree on waiting on more feedback from the release team before landing though

I don't really mind, but I have a question on how this will impact the release process commits-wise...

Currently we do two commits, both of which are the only un-signed-off commits people are regularly allowed to do. (Some leeway is given for if releasers mess up and have to fix links or something afterwards.)

Does this mean we add a third commit before? e.g:

Update new API released: info
Changelog & node_version.h (This is the tagged commit)
Reset node_version.h for the next release

Or do we just roll this into the Changelog commit?

I don't see anything wrong with rolling it into the Changelog commit.

Anybody from @nodejs/release want to give their thumbs up for this? :)

+1 to rolling it into the Changelog commit. And LGTM

Landed in 2cd99eb, e7f1c00. Thanks!

Add a `REPLACEME` tag that should be used when introducing docs for new features, so that they can be updated when releases are made. Ref: #6578 PR-URL: #6864 Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: Claudio Rodriguez <cjrodr@yahoo.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com>