doc: add a sentence about REPLACEME in code changes

[lance]

When adding to the REPL API recently, I was unsure what to put as a
version number for the new method I added. This change adds a reference
to releases.md where the use of REPLACEME is discussed.

Checklist

• documentation is changed or added
• commit message follows commit guidelines

[nodejs-github-bot]

@lance build started: https://ci.nodejs.org/blue/organizations/jenkins/node-test-pull-request-lite-pipeline/detail/node-test-pull-request-lite-pipeline/2525/pipeline

[lance]

This is a simple doc change. Any reason not to fast-track it?

[Trott]

Suggested change

	be sure to use `REPLACEME` for the version numbers as specified in
	use `REPLACEME` for the version number as specified in

[Trott]

To be honest, this sentence seems to come out of nowhere. There's no context explaining the YAML stuff etc. This might be more confusing than enlightening if a new person is reading it and doesn't already know about the YAML stuff. That said, having it documented is an improvement over not having it documented, so I'm totally OK with this landing as-is. But if there's a place to move this where it would have more context, that would be good. (Again, though, someone else can do that in a subsequent PR if the only goal here is to have it documented somewhere that a contributor might find it.)

An idea: Would it make sense to instead put this as a YAML comment in every doc/api/*.md file? That would put the information right where someone needs it at the time that they need it. On the other hand, that's a lot of copy/pasted text....
¯\(ツ)/¯

[Trott]

Suggested change

	`vcbuild.bat lint` on Windows). If you are adding to or deprecating the API,
	`vcbuild.bat lint` on Windows). If you are adding to or deprecating an API,

[Trott]

Maybe the only context that needs to be added is just a mention that this is referring to the YAML metadata?

If you are adding to or deprecating an API, use `REPLACEME`
for the version number in the documentation YAML metadata.

Probably no need to link to releases.md in that case?

[lance]

@Trott I don't think it would be that hard to add it as a comment in the YAML itself. E.g.

sed -i 's/^<!-- YAML*$/<!-- YAML\n# When adding to or deprecating an API, use \'REPLACEME\' for the version number/' doc/api/*.md

[richardlau]

An idea: Would it make sense to instead put this as a YAML comment in every doc/api/*.md file? That would put the information right where someone needs it at the time that they need it. On the other hand, that's a lot of copy/pasted text....
¯_(ツ)_/¯

My only concern here is whether the REPLACEME in the comment would also get replaced when a release was cut.

[Trott]

I think this is fast-track-able in its current form. Please 👍 here to approve fast-tracking.

[lance]

@Trott I inadvertently pushed this branch to nodejs/node instead of my fork. Not sure of the best way to deal with this, as I would rather not close this PR and start over. I am assuming that I can just delete the branch here on upstream once the PR is merged. Please advise if this is not the best route.

[Trott]

I am assuming that I can just delete the branch here on upstream once the PR is merged. Please advise if this is not the best route.

That seems like it would be fine to me.

[danbev]

Landed in 93a57c3.