From 7cc22e4e14568efa46f65a3066d2a0b36507bc9f Mon Sep 17 00:00:00 2001 From: Geoffrey Booth Date: Wed, 6 Mar 2024 14:12:01 -0800 Subject: [PATCH 1/7] doc: add policy for executables --- doc/contributing/distribution.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/doc/contributing/distribution.md b/doc/contributing/distribution.md index 4727c03b6924e5..f30d5e7ed1b0fb 100644 --- a/doc/contributing/distribution.md +++ b/doc/contributing/distribution.md @@ -25,3 +25,16 @@ only as a semver-major change, unless the related feature or project is documented as experimental. In addition, Node.js includes external projects as internal dependencies. These may be replaced or removed at any time, provided that doing so is not a breaking change. + +## Executables + +The Node.js distribution adds a number of executable commands into the user's +`PATH`, such as `node`. The distribution will only include executables that run +code that is vendored within the Node.js distribution. The distribution will not +include executables to run code that is downloaded after installation. + +For example, the distribution includes an `npm` executable to run the npm +package manager, which can be used to download other software, some of which may +create their own executables. The Node.js distribution will not include a `foo` +executable that would either directly download the full `foo` software or use +`npm` or Corepack to download `foo`. From ca2fa32554f899b886f18a0fe02584c4832b5006 Mon Sep 17 00:00:00 2001 From: Geoffrey Booth Date: Thu, 7 Mar 2024 07:16:37 -0800 Subject: [PATCH 2/7] reword --- doc/contributing/distribution.md | 9 ++------- 1 file changed, 2 insertions(+), 7 deletions(-) diff --git a/doc/contributing/distribution.md b/doc/contributing/distribution.md index f30d5e7ed1b0fb..9075a0c63b43d7 100644 --- a/doc/contributing/distribution.md +++ b/doc/contributing/distribution.md @@ -31,10 +31,5 @@ that doing so is not a breaking change. The Node.js distribution adds a number of executable commands into the user's `PATH`, such as `node`. The distribution will only include executables that run code that is vendored within the Node.js distribution. The distribution will not -include executables to run code that is downloaded after installation. - -For example, the distribution includes an `npm` executable to run the npm -package manager, which can be used to download other software, some of which may -create their own executables. The Node.js distribution will not include a `foo` -executable that would either directly download the full `foo` software or use -`npm` or Corepack to download `foo`. +include executables whose names refer to software that is not included in the +Node.js distribution. From bff9dbcc2a61bb0a571e3e3db265b41e4e7b4180 Mon Sep 17 00:00:00 2001 From: Geoffrey Booth Date: Thu, 7 Mar 2024 07:55:08 -0800 Subject: [PATCH 3/7] reword --- doc/contributing/distribution.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/doc/contributing/distribution.md b/doc/contributing/distribution.md index 9075a0c63b43d7..c1275b452f2ba0 100644 --- a/doc/contributing/distribution.md +++ b/doc/contributing/distribution.md @@ -29,7 +29,5 @@ that doing so is not a breaking change. ## Executables The Node.js distribution adds a number of executable commands into the user's -`PATH`, such as `node`. The distribution will only include executables that run -code that is vendored within the Node.js distribution. The distribution will not -include executables whose names refer to software that is not included in the -Node.js distribution. +`PATH`, such as `node`. The distribution will only include executables whose +names refer to software that is vendored within the Node.js distribution. From f939d263957c65d965888802de8b222fb4fd932c Mon Sep 17 00:00:00 2001 From: Geoffrey Booth Date: Thu, 7 Mar 2024 07:57:03 -0800 Subject: [PATCH 4/7] reword --- doc/contributing/distribution.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/contributing/distribution.md b/doc/contributing/distribution.md index c1275b452f2ba0..e4729a0facb119 100644 --- a/doc/contributing/distribution.md +++ b/doc/contributing/distribution.md @@ -28,6 +28,6 @@ that doing so is not a breaking change. ## Executables -The Node.js distribution adds a number of executable commands into the user's -`PATH`, such as `node`. The distribution will only include executables whose -names refer to software that is vendored within the Node.js distribution. +The Node.js distribution includes a number of executables, such as `node`. The +distribution will only include executables whose names refer to software that is +vendored within the Node.js distribution. From 54699e04c4446fe136a6e1831afb95fa903104b0 Mon Sep 17 00:00:00 2001 From: Geoffrey Booth Date: Thu, 7 Mar 2024 09:55:11 -0800 Subject: [PATCH 5/7] exclude executables that aren't provided for direct execution --- doc/contributing/distribution.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/doc/contributing/distribution.md b/doc/contributing/distribution.md index e4729a0facb119..6196be788680a7 100644 --- a/doc/contributing/distribution.md +++ b/doc/contributing/distribution.md @@ -28,6 +28,7 @@ that doing so is not a breaking change. ## Executables -The Node.js distribution includes a number of executables, such as `node`. The -distribution will only include executables whose names refer to software that is -vendored within the Node.js distribution. +The Node.js distribution includes a number of executables, such as `node`, that +are intended to be run directly by users. The distribution will only include +such executables whose names refer to software that is vendored within the +Node.js distribution. From 876390ffe87bafc0136eb881dcf6196c0a2facac Mon Sep 17 00:00:00 2001 From: Geoffrey Booth Date: Tue, 12 Mar 2024 08:48:56 -0700 Subject: [PATCH 6/7] shorten --- doc/contributing/distribution.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/doc/contributing/distribution.md b/doc/contributing/distribution.md index 6196be788680a7..6d4a593c5c4de1 100644 --- a/doc/contributing/distribution.md +++ b/doc/contributing/distribution.md @@ -28,7 +28,5 @@ that doing so is not a breaking change. ## Executables -The Node.js distribution includes a number of executables, such as `node`, that -are intended to be run directly by users. The distribution will only include -such executables whose names refer to software that is vendored within the -Node.js distribution. +The Node.js distribution includes only executables whose names refer to software +that is vendored within the Node.js distribution. From 18f397dbc0c36966d901d662e4eb1eef1dbd9dd0 Mon Sep 17 00:00:00 2001 From: Geoffrey Booth Date: Wed, 13 Mar 2024 14:34:40 -0700 Subject: [PATCH 7/7] add example --- doc/contributing/distribution.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/doc/contributing/distribution.md b/doc/contributing/distribution.md index 6d4a593c5c4de1..cb103117032c49 100644 --- a/doc/contributing/distribution.md +++ b/doc/contributing/distribution.md @@ -29,4 +29,7 @@ that doing so is not a breaking change. ## Executables The Node.js distribution includes only executables whose names refer to software -that is vendored within the Node.js distribution. +that is vendored within the Node.js distribution. For example, Node.js includes +an executable `npm` to run the npm software included within the Node.js +distribution; Node.js does not include a `foo` executable which would download +software named Foo.