Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

doc: add policy for “placeholder” executables #52107

Closed
wants to merge 4 commits into from
Closed

doc: add policy for “placeholder” executables #52107

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
e168807
doc: add policy for executables
GeoffreyBooth Mar 6, 2024
c3f405d
revise
GeoffreyBooth Mar 30, 2024
6268575
Update distribution.md
GeoffreyBooth Apr 3, 2024
ec1b3d0
Rewrap
GeoffreyBooth Apr 3, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
8 changes: 8 additions & 0 deletions doc/contributing/distribution.md
View file
Open in desktop
Expand Up @@ -25,3 +25,11 @@ 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.

## Placeholder executables

Installing Node.js will not create "placeholder" executables: commands that
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this wording is pretty vague. npx can be considered to be a placeholder executable according to this definition or at least some interpretations of it

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I really don't see that, especially with the examples. The npx executable runs npx, which is included in our distribution. Npx itself isn't getting downloaded, it's downloading other things. Likewise for npm and Corepack (when run via the corepack executable).

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So to be clear, that means this policy would not block use from shipping a corepack_yarn executable, correct?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It would block that. The policy says “refers to,” not “shares the exact same name as.” corepack_yarn refers to Yarn, just as download_yarn or download_and_install_yarn refer to Yarn.

Copy link
Contributor

@aduh95 aduh95 Mar 27, 2024 •
edited

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How does npx fits into this policy then? npx yarn downloads and executes Yarn, same as corepack_yarn would.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For npx yarn the executable is npx, which doesn’t refer to Yarn. The text says “Installing Node.js will not create ‘placeholder’ executables;” Installing Node doesn’t create an npx yarn executable, it creates an npx executable. You may use that executable to run a command to download and install Yarn, and that’s fine, but the executable itself doesn’t refer to Yarn. Installing Node creates a node executable too and there’s some node --eval command that can download and install Yarn, but I’m not intending to ban the node executable either.

I understand you’re looking for loopholes, and perhaps the language can be improved, but the intent of the PR is very clearly laid out in the description. If you want to suggest alternative language that is clearer or stronger, that’s fine, but as I said in the TSC meeting that introduced this PR, the point is less about the specific language then the fact that we reach an agreement about placeholder executables. If we can reach such a consensus, then we can move on to nail down the best possible language to express that.

refer to software that is not distributed with Node.js, but instead would be
downloaded when the command is run. For example, Node.js will not create a
`yarn` placeholder executable that will download Yarn when run or an `eslint`
placeholder executable that will download ESLint when run.