doc: updating REPLACEME tag during release

[gibfahn]

Checklist

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

Affected core subsystem(s)

doc

Description of change

Add a paragraph to the releases.md guide to document replacing the
REPLACEME tag with the release version for new APIs.

Ref: #6864 (comment), #6578

@addaleax@claudiorodriguez@evanlucas

[gibfahn]

@claudiorodriguez I wasn't sure what to add to CONTRIBUTING.md, it's quite a short document at the moment (which is a good thing IMO), and I guess people adding new APIs are probably already familiar with the contribution process.

[evanlucas]

Can we limit to 80 columns? Also, I believe the -i flag requires an argument on OS X. So something like sed -i "" "s/REPLACEME/$VERSION/g" doc/api/*.md

[jasnell]

For new additions to the doc, it would be preferred to avoid uses of words like we, you, etc. For instance, the first sentence can be reworded as "If this release includes new APIs, then it is necessary to document that those were first added in this version."

[jasnell]

s/REPLACEME/REPLACEME

[gibfahn]

@jasnell Done, thanks.

@evanlucas Should be 80 columns now. As for the sed problem, it seems that the OSX version is incompatible with the standard GNU version. Judging from these (one, two) Stack Overflow answers, it looks like the easiest method is to use the perl command instead (perl should be installed by default), or brew install gnu-sed.

Perl command: perl -pi -e "s/REPLACEME/$VERSION/g" doc/api/*.md

[addaleax]

LGTM if the release folks are happy, and I have made the experience that cross-platform sed -i is not really doable, too.

[jasnell]

LGTM

[mhdawson]

LTGM

[mhdawson]

@thealphanerd can you review/comment as a "release folk"

[evanlucas]

LGTM

[jasnell]

Landed in b10ee9d

[rvagg]

yikes .. you know this is going to get forgotten regularly and will require follow-up PRs to address it. Perhaps it's time to start scripting some of the release stuff, bumping version, ABI #, signed tagging, maybe even have something prompt with a checklist you have to answer to push a release out, it's getting kind of complicated.

[rvagg]

@nodejs/release note the new requirement for releases added in here

[addaleax]

@rvagg You’ve seen 2cd99eb?

[rvagg]

nope, obviously in my backlog that I haven't got to yet! thanks @addaleax, that should help