From b77e35fdb4b813a2d0540e946f7b94b00d00da6c Mon Sep 17 00:00:00 2001
From: Myles Borins <mylesborins@github.com>
Date: Wed, 21 Oct 2020 10:59:11 -0400
Subject: [PATCH 1/2] doc: update package.json field definitions

Only imports has the experimental status right now but technically all
ESM related features are currently experimental. The list also doesn't
appear to be in any specific order so I've grouped the experimental
features together.
---
 doc/api/packages.md | 56 ++++++++++++++++++++++++---------------------
 1 file changed, 30 insertions(+), 26 deletions(-)

diff --git a/doc/api/packages.md b/doc/api/packages.md
index 18bafb1c36685b..507468cdf9d2de 100644
--- a/doc/api/packages.md
+++ b/doc/api/packages.md
@@ -834,12 +834,12 @@ The following fields in `package.json` files are used in Node.js:
 
 * [`"name"`][] - Relevant when using named imports within a package. Also used
   by package managers as the name of the package.
+* [`"main"`][] - The default module when loading the package, if exports is not
+  specified, and in versions of Node.js prior to the introduction of exports.
 * [`"type"`][] - The package type determining whether to load `.js` files as
   CommonJS or ES modules.
 * [`"exports"`][] - Package exports and conditional exports. When present,
   limits which submodules can be loaded from within the package.
-* [`"main"`][] - The default module when loading the package, if exports is not
-  specified, and in versions of Node.js prior to the introduction of exports.
 * [`"imports"`][] - Package imports, for use by modules within the package
   itself.
 
@@ -871,6 +871,30 @@ _npm_ registry requires a name that satisfies
 The `"name"` field can be used in addition to the [`"exports"`][] field to
 [self-reference][] a package using its name.
 
+### `"main"`
+<!-- YAML
+added: v0.4.0
+-->
+
+* Type: {string}
+
+```json
+{
+  "main": "./main.js"
+}
+```
+
+The `"main"` field defines the script that is used when the [package directory
+is loaded via `require()`](modules.md#modules_folders_as_modules). Its value
+is interpreted as a path.
+
+```js
+require('./path/to/directory'); // This resolves to ./path/to/directory/main.js.
+```
+
+When a package has an [`"exports"`][] field, this will take precedence over the
+`"main"` field when importing the package by name.
+
 ### `"type"`
 <!-- YAML
 added: v12.0.0
@@ -882,6 +906,8 @@ changes:
     description: Unflag `--experimental-modules`.
 -->
 
+> Stability: 1 - Experimental
+
 * Type: {string}
 
 The `"type"` field defines the module format that Node.js uses for all
@@ -948,6 +974,8 @@ changes:
     description: Implement conditional exports.
 -->
 
+> Stability: 1 - Experimental
+
 * Type: {Object} | {string} | {string[]}
 
 ```json
@@ -969,30 +997,6 @@ referenced via `require` or via `import`.
 All paths defined in the `"exports"` must be relative file URLs starting with
 `./`.
 
-### `"main"`
-<!-- YAML
-added: v0.4.0
--->
-
-* Type: {string}
-
-```json
-{
-  "main": "./main.js"
-}
-```
-
-The `"main"` field defines the script that is used when the [package directory
-is loaded via `require()`](modules.md#modules_folders_as_modules). Its value
-is interpreted as a path.
-
-```js
-require('./path/to/directory'); // This resolves to ./path/to/directory/main.js.
-```
-
-When a package has an [`"exports"`][] field, this will take precedence over the
-`"main"` field when importing the package by name.
-
 ### `"imports"`
 <!-- YAML
 added: v14.6.0

From fe8e5b9454d30e5b42ef29fd15d1c1cf3e6aa6e5 Mon Sep 17 00:00:00 2001
From: Myles Borins <myles.borins@gmail.com>
Date: Thu, 22 Oct 2020 11:31:58 -0400
Subject: [PATCH 2/2] Update doc/api/packages.md

Co-authored-by: Rich Trott <rtrott@gmail.com>
---
 doc/api/packages.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/api/packages.md b/doc/api/packages.md
index 507468cdf9d2de..f1833783f121f6 100644
--- a/doc/api/packages.md
+++ b/doc/api/packages.md
@@ -886,7 +886,7 @@ added: v0.4.0
 
 The `"main"` field defines the script that is used when the [package directory
 is loaded via `require()`](modules.md#modules_folders_as_modules). Its value
-is interpreted as a path.
+is a path.
 
 ```js
 require('./path/to/directory'); // This resolves to ./path/to/directory/main.js.