doc: deprecate calling promisify on a function that returns a promise

[aduh95]

The plan is to have it throw a runtime warning in the next major, so it will help catch cases like #49607, and will likely never be EOL.

[github-actions]

The notable-change PRs with changes that should be highlighted in changelogs. label has been added by @aduh95.

Please suggest a text for the release notes if you'd like to include a more detailed summary, then proceed to update the PR description with the text or a link to the notable change suggested text comment.

[LiviaMedeiros]

The deprecation is about calling util.promisify() on such functions but we can emit warning only when the function returns it, right?

I wonder if it will be possible to trace the promisify() call itself with --trace-deprecation.

[aduh95]

@LiviaMedeiros that's correct, the reliable way to know if a function returns a promise is to call it. It's going to trace where the call to the promisified function happened, so given:

// file.js

const promisified = promisify(async () => {});

promisified();

node --trace-warnings file.js will show at file.js:5:1. Hopefully that will give enough info to debug it.

[LiviaMedeiros]

LGTM with pr-url fix.

[nodejs-github-bot]

Commit Queue failed

- Loading data for nodejs/node/pull/49647
✔  Done loading data for nodejs/node/pull/49647
----------------------------------- PR info ------------------------------------
Title      doc: deprecate calling `promisify` on a function that returns a promise (#49647)
   ⚠  Could not retrieve the email or name of the PR author's from user's GitHub profile!
Branch     aduh95:deprecate-promisify-async-function -> nodejs:main
Labels     doc, notable-change, author ready, deprecations
Commits    2
 - doc: deprecate calling `promisify` on a function that returns a promise
 - Apply suggestions from code review
Committers 2
 - Antoine du Hamel 
 - GitHub 
PR-URL: https://github.com/nodejs/node/pull/49647
Reviewed-By: Benjamin Gruenbaum 
Reviewed-By: LiviaMedeiros 
Reviewed-By: Trivikram Kamat 
------------------------------ Generated metadata ------------------------------
PR-URL: https://github.com/nodejs/node/pull/49647
Reviewed-By: Benjamin Gruenbaum 
Reviewed-By: LiviaMedeiros 
Reviewed-By: Trivikram Kamat 
--------------------------------------------------------------------------------
   ℹ  This PR was created on Thu, 14 Sep 2023 09:32:18 GMT
   ✔  Approvals: 3
   ✔  - Benjamin Gruenbaum (@benjamingr) (TSC): https://github.com/nodejs/node/pull/49647#pullrequestreview-1627341349
   ✔  - LiviaMedeiros (@LiviaMedeiros): https://github.com/nodejs/node/pull/49647#pullrequestreview-1627522210
   ✔  - Trivikram Kamat (@trivikr): https://github.com/nodejs/node/pull/49647#pullrequestreview-1629793683
   ✔  Last GitHub CI successful
   ℹ  Green GitHub CI is sufficient
--------------------------------------------------------------------------------
   ✔  No git cherry-pick in progress
   ✔  No git am in progress
   ✔  No git rebase in progress
--------------------------------------------------------------------------------
- Bringing origin/main up to date...
From https://github.com/nodejs/node
 * branch                  main       -> FETCH_HEAD
✔  origin/main is now up-to-date
- Downloading patch for 49647
From https://github.com/nodejs/node
 * branch                  refs/pull/49647/merge -> FETCH_HEAD
✔  Fetched commits as db8217b1bfe4..5a380cfe99d5
--------------------------------------------------------------------------------
[main c2d979e3e3] doc: deprecate calling `promisify` on a function that returns a promise
 Author: Antoine du Hamel 
 Date: Thu Sep 14 11:30:01 2023 +0200
 2 files changed, 20 insertions(+)
[main 3f477cf7d4] Apply suggestions from code review
 Author: Antoine du Hamel 
 Date: Thu Sep 14 20:25:23 2023 +0200
 2 files changed, 2 insertions(+), 2 deletions(-)
   ✔  Patches applied
There are 2 commits in the PR. Attempting autorebase.
Rebasing (2/4)
Executing: git node land --amend --yes

--------------------------------- New Message ----------------------------------

doc: deprecate calling promisify on a function that returns a promise
PR-URL: #49647

Reviewed-By: Benjamin Gruenbaum benjamingr@gmail.com

Reviewed-By: LiviaMedeiros livia@cirno.name

Reviewed-By: Trivikram Kamat trivikr.dev@gmail.com
[detached HEAD 92f9fdb2a5] doc: deprecate calling promisify on a function that returns a promise

Author: Antoine du Hamel duhamelantoine1995@gmail.com

Date: Thu Sep 14 11:30:01 2023 +0200

2 files changed, 20 insertions(+)

Rebasing (3/4)

Rebasing (4/4)
Executing: git node land --amend --yes

--------------------------------- New Message ----------------------------------

Apply suggestions from code review
Co-authored-by: Livia Medeiros livia@cirno.name

PR-URL: #49647

Reviewed-By: Benjamin Gruenbaum benjamingr@gmail.com

Reviewed-By: LiviaMedeiros livia@cirno.name

Reviewed-By: Trivikram Kamat trivikr.dev@gmail.com
[detached HEAD cd4ad065a6] Apply suggestions from code review

Author: Antoine du Hamel duhamelantoine1995@gmail.com

Date: Thu Sep 14 20:25:23 2023 +0200

2 files changed, 2 insertions(+), 2 deletions(-)
Successfully rebased and updated refs/heads/main.
ℹ  Add commit-queue-squash label to land the PR as one commit, or commit-queue-rebase to land as separate commits.

https://github.com/nodejs/node/actions/runs/6206595979

[nodejs-github-bot]

Landed in 71b90fa