doc: reorganize docs of module hooks and mark sync hooks as release candidate

[joyeecheung]

doc: mark sync module hooks as release candidate

doc: reorganize docs of module customization hooks

This reorganizes the documentation of module customization hooks
to promote the synchronous variant as it has fewer caveats.
Previously the documentation was organized as follows:

To do something:

1. For asynchronous hooks, do this, which may have these caveats
2. For synchronous hooks, do this, which does not have the caveats

To do something else:

1. For asynchronous hooks, do this, which may have these caveats
2. For synchronous hooks, do this, which does not have the caveats

It's now organized as follows:

Synchronous hooks:

• To do something, do this.
• To do something else, do this.
  (No mention that it doesn't have caveats, because users are not supposed
  to burden themselves with caveats in the other API that they do not
  use).

Asynchronous hooks:
They have these caveats, if they are too complex to deal with, consider
use the synchronous variant.

• To do something, do this, which may have these caveats.
• To do something, do this, which may have these caveats.

Refs: #56241

[nodejs-github-bot]

Review requested:

• @nodejs/loaders

[GeoffreyBooth]

Suggestions. Thank you for doing this.

[joyeecheung]

Rebased to resolve the conflicts and addressed reviews. PTAL, thanks @GeoffreyBooth

[joyeecheung]

Applied the suggestions. PTAL, thanks @GeoffreyBooth @aduh95

[nodejs-github-bot]

Commit Queue failed

- Loading data for nodejs/node/pull/60960
✔  Done loading data for nodejs/node/pull/60960
----------------------------------- PR info ------------------------------------
Title      doc: reorganize docs of module hooks and mark sync hooks as release candidate (#60960)
Author     Joyee Cheung <joyeec9h3@gmail.com> (@joyeecheung)
Branch     joyeecheung:sync-hooks-rc -> nodejs:main
Labels     doc, review wanted
Commits    3
 - doc: reorganize docs of module customization hooks
 - doc: mark sync module hooks as release candidate
 - fixup! doc: reorganize docs of module customization hooks
Committers 2
 - Joyee Cheung <joyeec9h3@gmail.com>
 - GitHub <noreply@github.com>
PR-URL: https://github.com/nodejs/node/pull/60960
Refs: https://github.com/nodejs/node/issues/56241
Reviewed-By: Geoffrey Booth <webadmin@geoffreybooth.com>
------------------------------ Generated metadata ------------------------------
PR-URL: https://github.com/nodejs/node/pull/60960
Refs: https://github.com/nodejs/node/issues/56241
Reviewed-By: Geoffrey Booth <webadmin@geoffreybooth.com>
--------------------------------------------------------------------------------
   ℹ  This PR was created on Fri, 05 Dec 2025 11:24:58 GMT
   ✔  Approvals: 1
   ✔  - Geoffrey Booth (@GeoffreyBooth): https://github.com/nodejs/node/pull/60960#pullrequestreview-3558822069
   ✔  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 60960
From https://github.com/nodejs/node
 * branch                  refs/pull/60960/merge -> FETCH_HEAD
✔  Fetched commits as 81e05e124f71..116abd0823f4
--------------------------------------------------------------------------------
Auto-merging doc/api/cli.md
Auto-merging doc/api/module.md
[main 0a64245be1] doc: reorganize docs of module customization hooks
 Author: Joyee Cheung <joyeec9h3@gmail.com>
 Date: Tue Dec 2 14:28:30 2025 +0800
 2 files changed, 513 insertions(+), 335 deletions(-)
Auto-merging doc/api/module.md
[main 459594c3f6] doc: mark sync module hooks as release candidate
 Author: Joyee Cheung <joyeec9h3@gmail.com>
 Date: Wed Dec 3 13:26:47 2025 +0800
 1 file changed, 6 insertions(+), 2 deletions(-)
Auto-merging doc/api/module.md
[main 5744595733] fixup! doc: reorganize docs of module customization hooks
 Author: Joyee Cheung <joyeec9h3@gmail.com>
 Date: Tue Dec 9 17:34:16 2025 +0100
 1 file changed, 5 insertions(+), 13 deletions(-)
   ✔  Patches applied
There are 3 commits in the PR. Attempting autorebase.
(node:2246) [DEP0190] DeprecationWarning: Passing args to a child process with shell option true can lead to security vulnerabilities, as the arguments are not escaped, only concatenated.
(Use `node --trace-deprecation ...` to show where the warning was created)
Rebasing (2/5)
Rebasing (3/5)
Executing: git node land --amend --yes
--------------------------------- New Message ----------------------------------
doc: reorganize docs of module customization hooks
This reorganizes the documentation of module customization hooks

to promote the synchronous variant as it has fewer caveats.

Previously the documentation was organized as follows:
To do something:

For asynchronous hooks, do this, which may have these caveats
For synchronous hooks, do this, which does not have the caveats

To do something else:

For asynchronous hooks, do this, which may have these caveats
For synchronous hooks, do this, which does not have the caveats

It's now organized as follows:
Synchronous hooks:

To do something, do this.

To do something else, do this.

(No mention that it doesn't have caveats, because users are not supposed

to burden themselves with caveats in the other API that they do not

use).
Asynchronous hooks:

They have these caveats, if they are too complex to deal with, consider

use the synchronous variant.
To do something, do this, which may have these caveats.

To do something, do this, which may have these caveats.
PR-URL: #60960

Refs: #56241

Reviewed-By: Geoffrey Booth <webadmin@geoffreybooth.com>
[detached HEAD 4807155eff] doc: reorganize docs of module customization hooks

Author: Joyee Cheung <joyeec9h3@gmail.com>

Date: Tue Dec 2 14:28:30 2025 +0800

2 files changed, 505 insertions(+), 335 deletions(-)

Rebasing (4/5)

Rebasing (5/5)

Executing: git node land --amend --yes

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

doc: mark sync module hooks as release candidate
PR-URL: #60960

Refs: #56241

Reviewed-By: Geoffrey Booth <webadmin@geoffreybooth.com>
[detached HEAD eaca4c8c12] doc: mark sync module hooks as release candidate

Author: Joyee Cheung <joyeec9h3@gmail.com>

Date: Wed Dec 3 13:26:47 2025 +0800

1 file changed, 6 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/20174007589

[nodejs-github-bot]

Landed in 81e05e1...28b1139