doc: lint deprecation codes

[aduh95]

Add a rule to make sure deprecation codes are in order. This is to discourage the use of placeholders by contributors when creating new deprecations, and to relieve authors the responsibility to swap them with the appropriate code on landing.

Suggested by @targos in #33430 (comment).

Blocked by #33430.

Checklist

• make -j4 test (UNIX), or vcbuild test (Windows) passes
• tests and/or benchmarks are included
• documentation is changed or added
• commit message follows commit guidelines

[richardlau]

Is it possible to implement this as a lint rule as opposed to a new tool and test?

[aduh95]

Is it possible to implement this as a lint rule as opposed to a new tool and test?

@richardlau Do you have an example I can follow on how to implement that? I'm not familiar with markdown linters (yet 😅).

[richardlau]

https://github.com/nodejs/node/blob/master/tools/eslint-rules/documented-errors.js, for example.

Ah wait that is a js lint rule. I think the custom markdown lint rules are external to this repo. Cc @Trott

[BridgeAR]

@richardlau we could lint that all deprecation codes adhere to a specific format in lib.

[aduh95]

@richardlau we could lint that all deprecation codes adhere to a specific format in lib.

That would cover runtime deprecation only right?

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/32208/

[Trott]

Ah wait that is a js lint rule. I think the custom markdown lint rules are external to this repo. Cc @Trott

They are in https://github.com/nodejs/remark-preset-lint-node.

[aduh95]

Do we still want to do that? Every now and then a new PR appears to replace DEPXXX placeholders that made their way to master, but on the other hand the tooling is supposed to take care of it now…

I personally don't get why we use a placeholder, because if a new deprecation lands before the one on the PR, the author still has to fix the git conflict, so the placeholder doesn't help there. If someone thinks it's still a valid idea, I'm willing to work on it, otherwise let's close this.

[github-actions]

This issue/PR was marked as stalled, it will be automatically closed in 30 days. If it should remain open, please leave a comment explaining why it should remain open.

[Trott]

I personally don't get why we use a placeholder, because if a new deprecation lands before the one on the PR, the author still has to fix the git conflict, so the placeholder doesn't help there. If someone thinks it's still a valid idea, I'm willing to work on it, otherwise let's close this.

In theory at least, one thing the placeholder gets us is prevention of duplicate DEP codes landing and nobody noticing.