chrisbolin · December 18, 2018 22:44 · Dec 18, 2018 · Dec 18, 2018 · Dec 18, 2018 · Dec 18, 2018
diff --git a/README.md b/README.md
@@ -24,4 +24,6 @@ Adds a yarn version to this repo that will be used _instead_ of local versions o
 
 ### Why?
 
-This prevent conflicting yarn features in `yarn.lock`. For example if developer A has `[email protected]` it will write `integrity` checks into the file. If developer B has `[email protected]`, it will constantly _remove_ those features, which means that every install gets a different yarn lock.
+Consistency and reproducibility!  
+
+This also prevent conflicting yarn features in `yarn.lock`. For example if developer A has `[email protected]` it will write `integrity` checks into the file. If developer B has `[email protected]`, it will constantly _remove_ those features, which means that every install gets tons of unrelated changes to `yarn.lock`. `yarn.lock` merge conflicts can be _very_ hard to sort out, so it's best to remove this noise.
diff --git a/README.md b/README.md
@@ -2,7 +2,7 @@
 
 Adds a yarn version to this repo that will be used _instead_ of local versions of yarn. This will keep things consistent. There are a few steps here:
 
-- add a single-file yarn js bundle (version 1.12.3) to `./yarn-1.12.3.js` from https://github.com/yarnpkg/yarn/releases (choose 1.12.3 as it was more stable than 1.13.0 which was _just_ released). This is all of yarn (and all of it's dependencies) in a single JS file.
+- add a single-file yarn js bundle (version 1.12.3) to `./yarn-1.12.3.js` from [yarn/releases](https://github.com/yarnpkg/yarn/releases) (choose 1.12.3 as it was more stable than 1.13.0 which was _just_ released). This is all of yarn (and all of it's dependencies) in a single JS file.
 - add `yarnrc` file with a `yarn-path` entry that points to the above file
 - require yarn `1.0.0` in `package.json`'s `engines`, as _only yarn 1.0.0_ will support deferring commands to the `yarn-path`
 - extra credit: remove double dash (`--`) in yarn in `package.json` scripts, as this give annoying warnings in yarn 1+ (and now we'll all be on the same version).

diff --git a/.yarnrc b/.yarnrc
@@ -0,0 +1 @@
+yarn-path "./yarn-1.12.3.js" 
diff --git a/README.md b/README.md
@@ -0,0 +1,27 @@
+### Summary
+
+Adds a yarn version to this repo that will be used _instead_ of local versions of yarn. This will keep things consistent. There are a few steps here:
+
+- add a single-file yarn js bundle (version 1.12.3) to `./yarn-1.12.3.js` from https://github.com/yarnpkg/yarn/releases (choose 1.12.3 as it was more stable than 1.13.0 which was _just_ released). This is all of yarn (and all of it's dependencies) in a single JS file.
+- add `yarnrc` file with a `yarn-path` entry that points to the above file
+- require yarn `1.0.0` in `package.json`'s `engines`, as _only yarn 1.0.0_ will support deferring commands to the `yarn-path`
+- extra credit: remove double dash (`--`) in yarn in `package.json` scripts, as this give annoying warnings in yarn 1+ (and now we'll all be on the same version).
+
+### How to test
+
+- *do not upgrade your yarn version.* This should workflow should be doable with any yarn version.
+- all of the yarn commands should work: `yarn install`, `yarn test`, `yarn run some-script`...
+- run `yarn -v`. should be `1.12.3`
+- go out of this directory (e.g. `cd ~`) and run `yarn -v`. should be your local version *NOT* `1.12.3` (unless you just so happen to have this exact version installed locally). 
+
+### How it works
+
+`[email protected]` can defer execution to any yarn version included with the code, as called out in `.yarnrc`.
+- you run a yarn command, like `yarn install` or `yarn run some-script`
+- IF you have yarn >= `1.0.0` it will look for a `./.yarnrc` file, and if it finds a `yarn-path` entry it will _defer all yarn commands_ to that file. In this case it's `./yarn-1.12.3.js`. 
+- ELSE yarn `0.x` will just continue on as normal, but...
+-  whichever yarn version is running will check `package.json` `engines` and ensure that it meets the criterion. In this case, `>=1.0.0`. If it does not, it will fail and bail out. This prevents a user with an old version of yarn from messing up the system.
+
+### Why?
+
+This prevent conflicting yarn features in `yarn.lock`. For example if developer A has `[email protected]` it will write `integrity` checks into the file. If developer B has `[email protected]`, it will constantly _remove_ those features, which means that every install gets a different yarn lock.
diff --git a/package.json b/package.json
@@ -0,0 +1,7 @@
+{
+  ...
+  "engines": {
+    "yarn": ">=1.0.0"
+  },
+  ...
+}
diff --git a/yarn-1.12.3.js b/yarn-1.12.3.js
@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+module.exports =
+/******/ (function(modules) { // webpackBootstrap
+/******/        // The module cache
+/******/        var installedModules = {};
+/* truncated ~4MB file */