docs: add docs on yarn version management

[jakebolam]

Implements: #848

Add docs for users who need to manage yarn versions per project.

[DanBuild]

Deploy preview for yarnpkg ready!

Built with commit d305238

https://deploy-preview-896--yarnpkg.netlify.com

[DanBuild]

Deploy preview for yarnpkg ready!

Built with commit 29de7e9

https://deploy-preview-896--yarnpkg.netlify.com

[Haroenv]

@arcanis @Dan15, what do you think?

[arcanis]

Sounds duplicate with #895

Sounds like yvm also has little to offer compared to yarn policies set-version (wasn't actually aware of this tool before 😄), so we probably don't want to recommand it?

[jakebolam]

@arcanis we spoke of it in #848 back in July
@Daniel15 mentioned there was no integrity checking on download via the mirrors, which we've now added.

I could up-date these docs to include the newly created policy command too? (and note its only available since yarn 1.13)

[jakebolam]

Ultimately looks like we're trying to solve the same problem differently. Curious to the motivation behind having the tool version itself?

[msrose]

There does seem to be some overlap between these docs and the yarn policies docs, but I do think yvm offers a viable alternative for those who don't want to commit yarn releases to their repositories. Familiarity with tools like nvm/rvm/pyenv/rbenv/etc. is another reason to consider something like yvm.

Maybe augmenting the yarn policies docs with a link to yvm is a better option than a completely separate docs page, while making sure to include a note that yvm is a community tool and doesn't receive direct support from the yarn team?

[arcanis]

Curious to the motivation behind having the tool version itself?

Not relying on the network is a very common use case that's sometimes hard for people to figure out. Having an easy way to fill the need doesn't cost us much and bring a lot of value. Additionally, we want people to use the latest releases as much as possible (so that we don't get as many already-obsolete issues), so an easy upgrade path helps us maintaining Yarn.

Overall, I would avoid recommending third-parties on the Yarn documentation in general, and even more so when they are an alternative to something that's already supported. That would just bring confusion and possible security risks (we have no control on yvm).

That said, maybe the solution to your problem would be to bring to Yarn what yvm does right. Maybe it'll be out of scope for Yarn, but we can certainly discuss it in the code repository 😉

[jakebolam]

Thanks for all the feedback @arcanis
Having both options is great (not everyone is super keen on committing binaries to their projects, and yvm solves this)

Overall, I would avoid recommending third-parties on the Yarn documentation in general, and even more so when they are an alternative to something that's already supported. That would just bring confusion and possible security risks (we have no control on yvm).

Understandable not to support 3rd party libraries officially. We are open to giving the yarn core team write access to the yvm project.

Not relying on the network is a very common use case that's sometimes hard for people to figure out. Having an easy way to fill the need doesn't cost us much and bring a lot of value. Additionally, we want people to use the latest releases as much as possible (so that we don't get as many already-obsolete issues), so an easy upgrade path helps us maintaining Yarn.

I do feel yvm has a similar level of offline support, and an easy upgrade path as well. We should all strive to run the latest version of yarn.

[Bessonov]

Disclaimer: I'm yarn newbie and I'm not sure I want to stick with it.

I think this is off topic, but both ways are not optimal. Or I'm missing something.

Assume fresh workspace with existing project:

apt-get update > /dev/null && apt-get install -y curl unzip > /dev/null
echo "v10.15.3" > .nvmrc
echo 'yarn-path ".yarn/releases/yarn-1.12.3.js"' > .yarnrc
echo "1.12.3" > .yvmrc

Installation of node/npm with nvm:

curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.34.0/install.sh | bash
. /root/.bashrc
nvm install
Found '/tmp/test/.nvmrc' with version <v10.15.3>
Downloading and installing node v10.15.3...

As you can see, if .nvmrc exist, I just run nvm install to get desired version. Check.

I'm not sure that this both are very intuitive:

curl -o- -L https://yarnpkg.com/install.sh | bash
> Successfully installed Yarn 1.13.0!

. /root/.bashrc
yarn --version
internal/modules/cjs/loader.js:584
    throw err;
    ^

Error: Cannot find module '/tmp/test/.yarn/releases/yarn-1.12.3.js'

Why someone want to have yarn-1.12.3.js in repository? It's like to commit extracted maven binary... No way.

Of course I can look at .yarnrc and take appropriate actions. But it doesn't feels right. Furthermore, yarn policies breaks yvm.

And similar

curl -fsSL https://raw.githubusercontent.com/tophat/yvm/master/scripts/install.sh | INSTALL_VERSION="v2.4.0" bash
. /root/.bashrc
yvm install
You have provided an invalid version number. use "yvm ls-remote" to see valid versions.
Error: Invalid version number provided

But unexpected for me:

yvm use    
Installing yarn v1.12.3 in /root/.yvm

Not relying on the network is a very common use case that's sometimes hard for people to figure out.

Sorry, but I don't care about it. I have everything on multiple laptops, CI cache, proxies and even packaged into development (yes, I do) and build images for Jenkins. I prefer to have a clean git history.

That said, maybe the solution to your problem would be to bring to Yarn what yvm does right.

A huge +1 to fix yarn instead of 3rd party tools. And yes, for me nvm, sdkman, yvm and friends are workarounds, not solutions.

[arcanis]

Why someone want to have yarn-1.12.3.js in repository? It's like to commit extracted maven binary... No way.

While I understand where you're coming from, reconsider this "no way" and put in perspective the advantages versus the cons.

Pros:

• No need to actually download Yarn
• No need to make sure it's the right version of Yarn
• "I prefer to have a clean git history" - it gives you the best git history - you can checkout any commit from your history and know for sure that you will use the same Yarn version you used at the time.

Cons:

• It takes some space on the repository.

Do you prefer your application to work without hassle in a consistent way by default, or to spare a few KB in your repository?

[Bessonov]

you can checkout any single commit from your history and be 100% that you will use the Yarn version you configured at the time.

What about node_modules? This is more important than yarn or like (o:

Your pros and cons are all valid, that's not the question. And for every pro and con there is an answer. It's even not about to save ~4.5MB on every yarn update. But more about to have clean log, diff while debugging, merging, rebasing, code review and tooling like gitlab, gerrit and so on. I'm sure, that some of this tools supports excludes, but 1. not all tools and 2. I don't want to spend time to figure it out.

It's more about weights between pros and cons. And unfortunately, it's not enough to have it in repository. You still need to run commands to get it into PATH.

What's about something like:

echo "v1.12.3" > .yarnrc
curl -o- -L https://yarnpkg.com/install.sh | bash
> Found '/tmp/test/.yarnrc' with version <v1.12.3>
> .yarn/releases/yarn-1.12.3.js not found
> Download yarn-1.12.3.js
> Successfully installed Yarn 1.12.3!

yarn --version
> v1.12.3

yarn install
> Found '/tmp/test/.yarnrc' with version <v1.12.3>
> .yarn/releases/yarn-1.12.3.js found, nothing to do!

So you can decide to add yarn to repository or to ignore it.

[arcanis]

What about node_modules? This is more important than yarn or like (o:

It's funny you mention that 🤡

Now you must think I'm some kind of mad man - but really, consider what's the real reason is for not committing your node_modules. Why do we commit our sources but not our third-parties? You answered it before: VCS simply wouldn't support it. Upgrading a dependency would generate huge diffs with literally thousands of files moving around, and thousand others being diff'd.

But if you instead check-in exactly one file per package you use (the compressed package), and if you put them in a flat directory structure, the equation becomes very different - VCS are actually pretty good at this! We actually use this feature in the Yarn v2 repository, and I encourage you to clone the repository and see by yourself whether the increased time in noticeable.

We have some improvements to do (we generate a few extra symlinks I'd like to remove once Node gets to implement its Loaders API), but this should give you an idea of the vision I pursue.

But more about to have clean log, diff while debugging, merging, rebasing, code review and tooling like gitlab, gerrit and so on.

From my experience (I also integrate Yarn within the FB infra), checking-in Yarn in our repository was entirely beneficial, including from a tooling and history perspective. I have complete control over which version everyone is using, problems are solved with a simple "rebase on master please", and the upgrades can actually be reviewed precisely because they are in the history.

[arcanis]

It's more about weights between pros and cons. And unfortunately, it's not enough to have it in repository. You still need to run commands to get it into PATH.

Note that you need to have a Yarn in the PATH - any version starting from 1.0 is enough (that's august 2017).

[Bessonov]

You try to solve problems, which I never had :)

[Bessonov]

I'm using yvm for a while now and I'm pretty happy with it. What's about to add a community page and mention projects such as yvm?

Note that you need to have a Yarn in the PATH - any version starting from 1.0 is enough (that's august 2017).

No, thanks. For some time I use this way to work. Well, it's still not perfect, but it saves me from a lot of burden.