docs: Spell out "Install from Git repository" options properly #578
Conversation
|
|
|
@MichalBryxi is attempting to deploy a commit to the pnpm Team on Vercel. A member of the Team first needs to authorize it. |
|
Happy to talk about any and all choices and alter things if necessary, but I firmly believe that this amount of verboseness greatly reduces user confusion as they don't have to guess what is possible / why / how. |
| ``` | ||
| pnpm add github:zkochan/is-negative | ||
| pnpm add bitbucket:pnpmjs/git-resolver | ||
| pnpm add gitlab:pnpm/git-resolver |
There was a problem hiding this comment.
Is there more? I found only those in tests.
| * commit: `pnpm add kevva/is-positive#97edff6f525f192a3f83cea1944765f769ae2678` | ||
| * branch: `pnpm add kevva/is-positive#master` | ||
| * version range: `pnpm add kevva/is-positive#semver:^2.0.0` | ||
| ``` |
There was a problem hiding this comment.
Personally I prefer these triple-fenced examples, as they are way easier to target with a mouse for copy&pasting as you're constrained by the newlines. As opposed to the bullet point format above, which allows for copying the non-code prefix as well.
There was a problem hiding this comment.
you can have both. code sections inside bullet points. I don't think there's a reason to move the descriptions into the code blocks.
There was a problem hiding this comment.
No hard feelings, I can revert it, but to show why I'm against copy&paste examples in inline form: Here you can see how precise I have to be to select exactly what I intended:
Compare it to the code-fence version that has the full line for mousing around and thus it's way harder to select unwanted things:
There was a problem hiding this comment.
I pushed the revert to adhere to the ways it was. Let me know if it works for you now.
There was a problem hiding this comment.
But you could do it like this:
* Strict semver:
`` `
pnpm add zkochan/is-negative#semver:1.0.0
`` `
There was a problem hiding this comment.
Oooh, yeah why not. Pushed given change for both blocks. Also I used "Sentence case:" for the bullet points. Let me know if this works for you.
|
|
||
| You may also install just a subdirectory from a Git-hosted monorepo. For instance: | ||
| You can specify version (range) to install using the `semver:` parameter. For example: |
There was a problem hiding this comment.
I consider the semver: and path: (below) being explicitly spelled out very important. It makes sure that the user knows it's a keyword and not just a random thing in given repo.
docs/cli/add.md
Outdated
| * branch: `pnpm add kevva/is-positive#master` | ||
| * version range: `pnpm add kevva/is-positive#semver:^2.0.0` | ||
| ``` | ||
| # latest commit from default branch |
There was a problem hiding this comment.
As far as I can tell pnpm does not look for master per-se, it looks for (in GitHub terminology) default branch, hence the naming change here.
| pnpm add gitlab:pnpm/git-resolver | ||
| ``` | ||
|
|
||
| If `[provider]:` is omited, it defaults to `github:`. |
There was a problem hiding this comment.
IMO important to know the default here.
| * commit: `pnpm add kevva/is-positive#97edff6f525f192a3f83cea1944765f769ae2678` | ||
| * branch: `pnpm add kevva/is-positive#master` | ||
| * version range: `pnpm add kevva/is-positive#semver:^2.0.0` | ||
| ``` |
There was a problem hiding this comment.
you can have both. code sections inside bullet points. I don't think there's a reason to move the descriptions into the code blocks.
- Create sections to make visual/logical distinction of individual parts. - Spell out all major possible syntaxes. - Add more explanation to individual parts of the `URL` like `semver:` and `path:`. - Copy & paste examples directly from [tests](https://github.com/pnpm/pnpm/blob/main/resolving/git-resolver/test/index.ts) so that we're reasonably sure they are correct. - Explain defaults. - Explain common cases like monorepo & forks. Fixes: pnpm#577
- Adhere to current way of bullet pointed examples
MichalBryxi
force-pushed
the
mb/577-improve-pnpm-add-git-url-docs
branch
from
d3521c4
to
7c1d336
Compare
- That and making the bullets sentence-case
- That and making the bullets sentence-case
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
|
|
Preview looks reasonable (to me). |
|
merged 2be27c0 |
URLlikesemver:andpath:.Fixes: #577