--pending-deprecation process is underdocumented

[ChALkeR]

Currently, there are at least three peaces of documentation mentioning deprecations:

1. doc/api/deprecations.md
2. COLLABORATOR_GUIDE.md#deprecations
3. doc/api/cli.md (--(no|trace|throw|pending)-deprecation flags) (and a similar man page).

--pending-deprecation process is not documented in the first two of those, it's only documented as a cli switch that turns on some pending deprecations. Users have no way of knowing, without going to the source code and/or issues, which deprecations are revealed by that flag and which are not.

Curently, that's only DEP0005 — (#11968).

Per #12519, not all doc-deprecated api should support --pending-deprecation (i.e. I don't think that --pending-deprecation is a good idea for things that don't have a replacement yet and no concrete future plans of runtime-deprecation).

My opinion is that:

1. Fixed in c276851 (doc: improve --pending-deprecation documentation #18433). --pending-deprecation is a subclass of doc-deprecation and should be mentioned in the COLLABORATOR_GUIDE.md#deprecations as such (e.g. «Documentation-Only Deprecation … Documentation-only deprecations may trigger a runtime warning when launched with --pending-deprecation flag».
2. Fixed in 4efde4d (doc: improve --pending-deprecation documentation #18433). doc/api/deprecations.md should be kept in sync with --pending-deprecation, by specifing which of the doc-deprecations trigger a warning under that flag. See util: introduce util.types.is[…] type checks #18415 (comment).
3. Currently doc-deprecated APIs should be reviewed by TSC for adding a --pendining-deprecation (I suggest the criteria «has a working replacement or concrete plans for future runtime-deprecation»).
4. All new doc-deprecations should support --pending-deprecation, where possible. We don't doc-deprecate things not matching the criteria above anymore, do we?

@nodejs/tsc thoughs?

[Trott]

Not sure if this question belongs here or should go elsewhere. Gentle redirection welcome. Here we go: IIRC, there was disagreement when --pending-deprecation was added over just how much we could expect people to actually use it. I don't suppose anyone has any reasonably reliable indicators? It would be good to get an idea of the value here when compared to the cost.

[ChALkeR]

@Trott, well, it currently is not mentioned in any of the deprecation-relates documentation files, and users have no idea which actual deprecations does it reveal. I would be surprised if it's heavily used ;-).

Imo, the cost of supporting --pending-deprecation would be low, as there is very little code difference and actual runtime deprecation that would be implemented later on either way.

I don't think that we can expect everyone to use it, but it provides a good mechanism for package authors to quickly notice forthcoming runtime-deprecations without their users being hit by those by default.

Btw, @MylesBorins — does citgm track deprecation warnings and can it be run with --pending-deprecation flag?

[ChALkeR]

Filed #18433 as a start.

[ChALkeR]

Steps 1-2 closed by #18433.