--pending-deprecation process is underdocumented
Currently, there are at least three peaces of documentation mentioning deprecations:
- doc/api/deprecations.md
- COLLABORATOR_GUIDE.md#deprecations
-
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:
-
Fixed in c276851b (#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». -
Fixed in 4efde4d0 (#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 https://github.com/nodejs/node/pull/18415#discussion_r164295164. - 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»). - 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?