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

doc: mention corepack prepare supports dist-tag #44646

Merged
merged 5 commits into from
Oct 10, 2022
Merged

doc: mention corepack prepare supports dist-tag #44646

Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
0ec4131
doc: corepack prepare: dist-tag option
mrienstra Sep 15, 2022
850a30d
collapsed reference link as per @aduh95
mrienstra Sep 15, 2022
d453fb2
docs: several examples, as per @aduh95
mrienstra Sep 15, 2022
0a61bbe
docs: simplify, just say 'tag or range', drop link
mrienstra Sep 15, 2022
3feef21
docs: corepack: revert ref re-ordering
mrienstra Sep 16, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions doc/api/corepack.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,12 @@ package manager version you wish to set:
corepack prepare yarn@x.y.z --activate
```

Alternately, a [`dist-tag`](https://docs.npmjs.com/downloading-and-installing-packages-locally#installing-a-package-with-dist-tags) may be used:

```bash
corepack prepare yarn@latest --activate
Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
corepack prepare yarn@latest --activate
corepack prepare yarn@stable --activate

@latest is not a valid tag for yarn.

Copy link
Member

Choose a reason for hiding this comment

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

What do you mean? @latest is always a valid tag on npm (it cannot be deleted).

Copy link
Contributor

Choose a reason for hiding this comment

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

Yarn Berry is not on npm:

$ corepack prepare yarn@latest           
(node:96490) [DEP0005] DeprecationWarning: Buffer() is deprecated due to security and usability issues. Please use the Buffer.alloc(), Buffer.allocUnsafe(), or Buffer.from() methods instead.
(Use `node --trace-deprecation ...` to show where the warning was created)
Usage Error: Tag not found (latest)

$ corepack prepare yarn@stable
(node:96513) [DEP0005] DeprecationWarning: Buffer() is deprecated due to security and usability issues. Please use the Buffer.alloc(), Buffer.allocUnsafe(), or Buffer.from() methods instead.
(Use `node --trace-deprecation ...` to show where the warning was created)
Preparing yarn@stable...

Copy link
Member

Choose a reason for hiding this comment

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

In that case, it would be confusing to point to the npmjs documentation about dist-tags, no?

Copy link
Contributor

Choose a reason for hiding this comment

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

Yeah, using a link is probably not necessary. And maybe better not to use Yarn in the example since it's the odd one out?

Copy link
Contributor

Choose a reason for hiding this comment

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

We can also have several examples, e.g.:

```bash
corepack prepare pnpm@latest --activate
corepack prepare yarn@stable --activate
```

Copy link
Contributor Author

Choose a reason for hiding this comment

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

@aduh95, I like that ("several examples"), just pushed a commit to change it to that.

FYI, when I run prepare with yarn stable & latest (node v18.9.0, corepack 0.14.0, starting with Yarn 3.2.3), I get:
corepack prepare yarn@stable --activate --> Preparing yarn@stable for immediate activation..., still on Yarn 3.2.3 after.
corepack prepare yarn@latest --activate --> Usage Error: Tag not found (latest), still on Yarn 3.2.3 after (of course).

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Changed it to say "a tag or range may be used" instead of "a dist-tag may be used", since dist-tag is rarely specified in docs for npm, Yarn or pnpm. I think I was being too specific / low-level. Dropped the link as well.

Tempted to link to https://github.com/npm/node-semver#ranges, that's where /cli/v8/configuring-npm/package-json#dependencies links to.

There aren't any really great high-level docs for tags. /cli/v8/configuring-npm/package-json#dependencies links to /cli/v8/commands/npm-dist-tag, which isn't ideal (focused on modification, not usage), though I guess /cli/v8/commands/npm-dist-tag#purpose is nice. Considering expanding /downloading-and-installing-packages-locally#installing-a-package-with-dist-tags, maybe pulling some content from /cli/v8/commands/npm-dist-tag#purpose. Maybe I'll open an issue for that next week.

Copy link
Contributor

Choose a reason for hiding this comment

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

Tempted to link to https://github.com/npm/node-semver#ranges, that's where /cli/v8/configuring-npm/package-json#dependencies links to.

npm being one of the package managers, I think linking to SemVer rather than to npm would be preferable to not give a competitive adventage to one rather the others.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

@aduh95, I'll be out until Monday, feel free to link out to docs for tag and / or range if you think that would be helpful.

Still a little tempted to clarify when Corepack added support for using a tag or range (Corepack v0.120, which shipped with Node.js v18.6.0 and v16.17.0), but not sure if that should be formatted in a special way.

```

### Offline workflow

Many production environments don't have network access. Since Corepack
Expand Down