doc: recommend package exports instead of requiring folders

[aduh95]

Clarify that importing a folder is not supported by default, and add Legacy status to nudge users into using the more modern and versatile "exports" and/or "imports" fields in their package.json.

//cc @nodejs/modules

[nodejs-github-bot]

Review requested:

• @nodejs/modules

[bmeck]

This likely needs a warning that it will block access to adjacent things?

[ljharb]

Also, that this feature is the only practical way to make adding “exports” non-breaking.

[aduh95]

This likely needs a warning that it will block access to adjacent things?

Subpath imports does not encapsulate the package AFAIK; subpath exports does, but its documentation warns about that. Given that, I would say a warning is not needed here, but happy to reconsider if you disagree.

Also, that this feature is the only practical way to make adding “exports” non-breaking.

Hum, not sure about that, a more prudent approach is to always treat adding "exports" as a breaking change, I don't think we want the docs to give the impression it's not.

[nodejs-github-bot]

Commit Queue failed

- Loading data for nodejs/node/pull/41381
✔  Done loading data for nodejs/node/pull/41381
----------------------------------- PR info ------------------------------------
Title      doc: recommend package exports instead of requiring folders (#41381)
   ⚠  Could not retrieve the email or name of the PR author's from user's GitHub profile!
Branch     aduh95:no-require-folder -> nodejs:master
Labels     doc, module, author ready
Commits    2
 - doc: recommend package exports instead of requiring folders
 - Update doc/api/modules.md
Committers 2
 - Antoine du Hamel 
 - GitHub 
PR-URL: https://github.com/nodejs/node/pull/41381
Reviewed-By: James M Snell 
Reviewed-By: Geoffrey Booth 
------------------------------ Generated metadata ------------------------------
PR-URL: https://github.com/nodejs/node/pull/41381
Reviewed-By: James M Snell 
Reviewed-By: Geoffrey Booth 
--------------------------------------------------------------------------------
   ℹ  This PR was created on Sun, 02 Jan 2022 18:05:47 GMT
   ✔  Approvals: 2
   ✔  - James M Snell (@jasnell) (TSC): https://github.com/nodejs/node/pull/41381#pullrequestreview-854803616
   ✔  - Geoffrey Booth (@GeoffreyBooth): https://github.com/nodejs/node/pull/41381#pullrequestreview-854846838
   ✔  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/master up to date...
From https://github.com/nodejs/node
 * branch                  master     -> FETCH_HEAD
   50b7ab9659..f8f3d35bd6  master     -> origin/master
✔  origin/master is now up-to-date
master is out of sync with origin/master. Mismatched commits:
 - 5c0b717ab6 tools: add missing `.PHONY` and `.NOTPARALLEL` targets in `Makefile`
 - f8f3d35bd6 tools: add missing `.PHONY` and `.NOTPARALLEL` targets in `Makefile`
--------------------------------------------------------------------------------
HEAD is now at f8f3d35bd6 tools: add missing `.PHONY` and `.NOTPARALLEL` targets in `Makefile`
   ✔  Reset to origin/master
- Downloading patch for 41381
From https://github.com/nodejs/node
 * branch                  refs/pull/41381/merge -> FETCH_HEAD
✔  Fetched commits as f8f3d35bd639..9969b1c6ab44
--------------------------------------------------------------------------------
Auto-merging doc/api/modules.md
[master dff4d2532d] doc: recommend package exports instead of requiring folders
 Author: Antoine du Hamel 
 Date: Sun Jan 2 19:02:38 2022 +0100
 1 file changed, 10 insertions(+), 4 deletions(-)
Auto-merging doc/api/modules.md
[master 09b7fb7b5e] Update doc/api/modules.md
 Author: Antoine du Hamel 
 Date: Sun Jan 2 21:26:27 2022 +0100
 1 file changed, 1 insertion(+), 1 deletion(-)
   ✔  Patches applied
There are 2 commits in the PR. Attempting autorebase.
Rebasing (2/4)
Executing: git node land --amend --yes

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

doc: recommend package exports instead of requiring folders
PR-URL: #41381

Reviewed-By: James M Snell [email protected]

Reviewed-By: Geoffrey Booth [email protected]
[detached HEAD 72225b675e] doc: recommend package exports instead of requiring folders

Author: Antoine du Hamel [email protected]

Date: Sun Jan 2 19:02:38 2022 +0100

1 file changed, 10 insertions(+), 4 deletions(-)

Rebasing (3/4)

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

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

Update doc/api/modules.md
Co-authored-by: Tobias Nießen [email protected]
PR-URL: #41381

Reviewed-By: James M Snell [email protected]

Reviewed-By: Geoffrey Booth [email protected]
[detached HEAD 1d82ee977f] Update doc/api/modules.md

Author: Antoine du Hamel [email protected]

Date: Sun Jan 2 21:26:27 2022 +0100

1 file changed, 1 insertion(+), 1 deletion(-)
Successfully rebased and updated refs/heads/master.
ℹ  Use --fixupAll option, squash the PR manually or land the PR from the command line.

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

[nodejs-github-bot]

Landed in 56679eb