Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

--pending-deprecation process is underdocumented #18417

Closed
ChALkeR opened this issue Jan 28, 2018 · 5 comments
Closed

--pending-deprecation process is underdocumented #18417

ChALkeR opened this issue Jan 28, 2018 · 5 comments
Labels
deprecations Issues and PRs related to deprecations. meta Issues and PRs related to the general management of the project.

Comments

@ChALkeR
Copy link
Member

ChALkeR commented Jan 28, 2018 •
edited
Loading

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?
This was referenced Jan 28, 2018
Closed
Closed
@Trott
Copy link
Member

Trott commented Jan 29, 2018

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
Copy link
Member Author

ChALkeR commented Jan 29, 2018 •
edited
Loading

@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 ChALkeR mentioned this issue Jan 29, 2018
Merged
3 tasks
@ChALkeR
Copy link
Member Author

ChALkeR commented Jan 29, 2018

Filed #18433 as a start.

ChALkeR added a commit to ChALkeR/io.js that referenced this issue Jan 30, 2018
@ChALkeR
doc: add pending-deprecation to COLLABORATOR_GUIDE
c276851 
This is described as being a doc-only deprecation subset.

Refs: nodejs#18417
PR-URL: nodejs#18433
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Daniel Bevenius <daniel.bevenius@gmail.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
ChALkeR added a commit to ChALkeR/io.js that referenced this issue Jan 30, 2018
@ChALkeR
doc: add pending-deprecation to deprecations list
4efde4d 
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 <anna@addaleax.net>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Daniel Bevenius <daniel.bevenius@gmail.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
@ChALkeR
Copy link
Member Author

ChALkeR commented Jan 30, 2018

Steps 1-2 closed by #18433.

@ChALkeR ChALkeR mentioned this issue Feb 9, 2018
Closed
2 tasks
MylesBorins pushed a commit that referenced this issue Feb 20, 2018
@ChALkeR @MylesBorins
doc: add pending-deprecation to COLLABORATOR_GUIDE
8dc159d 
This is described as being a doc-only deprecation subset.

Refs: #18417
PR-URL: #18433
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Daniel Bevenius <daniel.bevenius@gmail.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
MylesBorins pushed a commit that referenced this issue Feb 21, 2018
@ChALkeR @MylesBorins
doc: add pending-deprecation to COLLABORATOR_GUIDE
99cbe44 
This is described as being a doc-only deprecation subset.

Refs: #18417
PR-URL: #18433
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Daniel Bevenius <daniel.bevenius@gmail.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
MylesBorins pushed a commit that referenced this issue Feb 21, 2018
@ChALkeR @MylesBorins
doc: add pending-deprecation to COLLABORATOR_GUIDE
8a627b1 
This is described as being a doc-only deprecation subset.

Refs: #18417
PR-URL: #18433
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Daniel Bevenius <daniel.bevenius@gmail.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
addaleax pushed a commit to addaleax/node that referenced this issue Feb 27, 2018
@ChALkeR @addaleax
doc: add pending-deprecation to deprecations list
dd917eb 
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 <anna@addaleax.net>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Daniel Bevenius <daniel.bevenius@gmail.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
@ChALkeR ChALkeR mentioned this issue Mar 24, 2018
Closed
MayaLekova pushed a commit to MayaLekova/node that referenced this issue May 8, 2018
@ChALkeR @MayaLekova
doc: add pending-deprecation to COLLABORATOR_GUIDE
301e3ad 
This is described as being a doc-only deprecation subset.

Refs: nodejs#18417
PR-URL: nodejs#18433
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Daniel Bevenius <daniel.bevenius@gmail.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
MayaLekova pushed a commit to MayaLekova/node that referenced this issue May 8, 2018
@ChALkeR @MayaLekova
doc: add pending-deprecation to deprecations list
d8bbf56 
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 <anna@addaleax.net>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Daniel Bevenius <daniel.bevenius@gmail.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
@ChALkeR
Copy link
Member Author

ChALkeR commented Oct 12, 2018

I believe this is outdated and can be closed now.

Adding --pending-deprecation support for doc-deprecated things could be done separately and we can have an ad-hoc discussion there.

@ChALkeR ChALkeR closed this as completed Oct 12, 2018
@ChALkeR ChALkeR added the meta Issues and PRs related to the general management of the project. label Oct 12, 2018
@ChALkeR ChALkeR added the deprecations Issues and PRs related to deprecations. label Oct 12, 2018
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
deprecations Issues and PRs related to deprecations. meta Issues and PRs related to the general management of the project.
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
2 participants
@ChALkeR @Trott