--pending-deprecation process is underdocumented #18417
Comments
|
Not sure if this question belongs here or should go elsewhere. Gentle redirection welcome. Here we go: IIRC, there was disagreement when |
|
@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 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 |
|
Filed #18433 as a start. |
This is described as being a doc-only deprecation subset. Refs: nodejs#18417 PR-URL: nodejs#18433 Reviewed-By: Anna Henningsen <[email protected]> Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Luigi Pinca <[email protected]> Reviewed-By: Daniel Bevenius <[email protected]> Reviewed-By: Rich Trott <[email protected]>
This adds a mention of `--pending-deprecation` flag effect in the Deprecated APIs document, and explicitly labels deprecations that support it. Refs: nodejs#18417 PR-URL: nodejs#18433 Reviewed-By: Anna Henningsen <[email protected]> Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Luigi Pinca <[email protected]> Reviewed-By: Daniel Bevenius <[email protected]> Reviewed-By: Rich Trott <[email protected]>
|
Steps 1-2 closed by #18433. |
This is described as being a doc-only deprecation subset. Refs: #18417 PR-URL: #18433 Reviewed-By: Anna Henningsen <[email protected]> Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Luigi Pinca <[email protected]> Reviewed-By: Daniel Bevenius <[email protected]> Reviewed-By: Rich Trott <[email protected]>
This is described as being a doc-only deprecation subset. Refs: #18417 PR-URL: #18433 Reviewed-By: Anna Henningsen <[email protected]> Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Luigi Pinca <[email protected]> Reviewed-By: Daniel Bevenius <[email protected]> Reviewed-By: Rich Trott <[email protected]>
This is described as being a doc-only deprecation subset. Refs: #18417 PR-URL: #18433 Reviewed-By: Anna Henningsen <[email protected]> Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Luigi Pinca <[email protected]> Reviewed-By: Daniel Bevenius <[email protected]> Reviewed-By: Rich Trott <[email protected]>
This adds a mention of `--pending-deprecation` flag effect in the Deprecated APIs document, and explicitly labels deprecations that support it. Refs: nodejs#18417 PR-URL: nodejs#18433 Reviewed-By: Anna Henningsen <[email protected]> Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Luigi Pinca <[email protected]> Reviewed-By: Daniel Bevenius <[email protected]> Reviewed-By: Rich Trott <[email protected]>
This is described as being a doc-only deprecation subset. Refs: nodejs#18417 PR-URL: nodejs#18433 Reviewed-By: Anna Henningsen <[email protected]> Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Luigi Pinca <[email protected]> Reviewed-By: Daniel Bevenius <[email protected]> Reviewed-By: Rich Trott <[email protected]>
This adds a mention of `--pending-deprecation` flag effect in the Deprecated APIs document, and explicitly labels deprecations that support it. Refs: nodejs#18417 PR-URL: nodejs#18433 Reviewed-By: Anna Henningsen <[email protected]> Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Luigi Pinca <[email protected]> Reviewed-By: Daniel Bevenius <[email protected]> Reviewed-By: Rich Trott <[email protected]>
|
I believe this is outdated and can be closed now. Adding |
ChALkeR
added
the
meta
Currently, there are at least three peaces of documentation mentioning deprecations:
--(no|trace|throw|pending)-deprecationflags) (and a similar man page).--pending-deprecationprocess 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-deprecationis a good idea for things that don't have a replacement yet and no concrete future plans of runtime-deprecation).My opinion is that:
--pending-deprecationdocumentation #18433).--pending-deprecationis 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».--pending-deprecationdocumentation #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: introduceutil.types.is[…]type checks #18415 (comment).--pendining-deprecation(I suggest the criteria «has a working replacement or concrete plans for future runtime-deprecation»).--pending-deprecation, where possible. We don't doc-deprecate things not matching the criteria above anymore, do we?@nodejs/tsc thoughs?
The text was updated successfully, but these errors were encountered: