Bug 1343928 - Switch from npm to yarn

Since it's faster, deterministic and doesn't given obscure errors when
using `--no-bin-links` (which is required for both npm and yarn on
Windows hosts), and as such unblocks the work in bug 1343624.

Many of the commands are the same as with npm. See:
https://yarnpkg.com/en/docs/usage

.travis.yml

@@ -44,16 +44,24 @@ matrix:
           - node_modules
       addons:
         firefox: latest
+      before_install:
+        # Required until Travis makes yarn available in the environment,
+        # since we override the default `install` for clarity.
+        - curl -sSfL https://yarnpkg.com/install.sh | bash
+        - export PATH=$HOME/.yarn/bin:$PATH
       install:
-        - npm install
+        # `--frozen-lockfile` will catch cases where people have forgotten to update `yarn.lock`.
+        # `--no-bin-links` is only necessary on Windows hosts, but we include here to ensure
+        # that the package.json scripts aren't relying on symlinks that won't exist elsewhere.
+        - yarn install --frozen-lockfile --no-bin-links
       before_script:
         # Required for Karma tests (http://docs.travis-ci.com/user/gui-and-headless-browsers/)
         - export DISPLAY=:99.0
         - sh -e /etc/init.d/xvfb start
       script:
-        - npm run lint
-        - npm test
-        - npm run build
+        - yarn run lint
+        - yarn test
+        - yarn run build
 
     # Job 3: Python Tests Chunk A
     - env: python-tests-main

bin/post_compile

@@ -6,7 +6,7 @@ echo $SOURCE_VERSION > ui/revision.txt
 
 # Create a `dist/` directory containing built/minified versions of the `ui/` assets.
 # Uses the node binaries/packages installed by the nodejs buildpack previously.
-npm run build
+yarn run build
 
 # Generate gzipped versions of files that would benefit from compression, that
 # WhiteNoise can then serve in preference to the originals. This is required
@@ -32,7 +32,7 @@ set-env NEW_RELIC_PROCESS_HOST_DISPLAY_NAME '$DYNO'
 
 # Remove nodejs files to reduce slug size (and avoid environment variable
 # pollution from the nodejs profile script), since they are no longer
-# required once `npm run build` has run. The buildpack cache will still
+# required once `yarn run build` has run. The buildpack cache will still
 # contain them, so this doesn't slow down the next slug compile.
 rm -r .heroku/node/
 rm -r .profile.d/nodejs.sh

docs/common_tasks.rst

@@ -123,32 +123,20 @@ To do this:
 
 * Tell people to visit: ``https://<your-username>.github.io/treeherder/ui/``
 
-There is no need to perform a ``npm run build`` prior. After switching away from the local gh-pages branch, you will need to recreate ``ui/js/config/local.conf.js`` if desired, due to the ``git add -f``.
+There is no need to perform a ``yarn run build`` prior. After switching away from the local gh-pages branch, you will need to recreate ``ui/js/config/local.conf.js`` if desired, due to the ``git add -f``.
 
 
-Updating packages in package.json
----------------------------------
+Updating package.json
+---------------------
 
-If the package is required in production/during deployment (ie: will be listed under
-`dependencies` rather than `devDependencies`), the following update process must be
-followed:
+* Always use ``yarn`` to make changes, not ``npm``, so that ``yarn.lock`` remains in sync.
+* Add new packages using ``yarn add <PACKAGE> --no-bin-links`` (``yarn.lock`` will be automatically updated).
+* After changes to ``package.json`` use ``yarn install --no-bin-links`` to install them and automatically update ``yarn.lock``.
+* For more details see the `Yarn documentation`_.
 
-* Follow the instructions for installing ``nodejs`` and ``build-essential`` `here <https://nodejs.org/en/download/package-manager/#debian-and-ubuntu-based-linux-distributions>`_, making sure to match the nodejs version specified in ``.travis.yml`` and ``package.json``.
+Note: To work around symlink issues for Windows hosts, use ``--no-bin-links`` with any command that adds/modifies packages. Whilst this is technically unnecessary with non-Windows hosts, it's still recommended since otherwise your local changes might inadvertently rely on ``node_modules/.bin/`` symlinks that won't exist in a newly created Vagrant environment. Unfortunately yarn doesn't yet support setting this option via the global yarn config, otherwise we could just enable it by default.
 
-* Update the package list in ``package.json``, making sure to specify an exact version, and not tilde or caret range notation.
-
-* From the root of the Treeherder repo, run:
-
-  .. code-block:: bash
-
-     > rm -rf node_modules npm-shrinkwrap.json
-     > npm install
-     # Adds the packages listed under ``dependencies`` to npm-shrinkwrap.json
-     > npm shrinkwrap
-
-* Now commit the changes to both ``package.json`` and ``npm-shrinkwrap.json``.
-
-Note: If the Vagrant host is Windows, the ``npm install`` will fail due to lack of symlink support on the host. You will need to temporarily move ``package.json`` outside of the shared folder and copy it and the resultant ``npm-shrinkwrap.json`` back when done.
+.. _Yarn documentation: https://yarnpkg.com/en/docs/usage
 
 
 Releasing a new version of the Python client

docs/deployment.rst

@@ -9,8 +9,8 @@ production, a minified/built version of the UI (generated using grunt) is used i
 
 To build the UI locally:
 
-* Install local dependencies by running ``npm install`` from the project root.
-* Run ``npm run build`` to create the ``dist`` directory.
+* Install local dependencies by running ``yarn install --no-bin-links`` from the project root.
+* Run ``yarn run build`` to create the ``dist`` directory.
 
 Then to serve assets from this directory instead of ``ui/``, in the Vagrant environment
 set ``SERVE_MINIFIED_UI=True`` before starting gunicorn/runserver.

docs/ui/installation.rst

@@ -12,8 +12,8 @@ Cloning the Repo
 Running the web-server
 ----------------------
 
-* Install `Node.js`_ if not present.
-* `npm install` to install all dependencies.
+* Install `Node.js`_ and Yarn_ if not present.
+* ``yarn install --no-bin-links`` to install all dependencies.
 * Open a shell, cd into the root of the repository you just cloned and type:
 
   .. code-block:: bash
@@ -53,8 +53,8 @@ We run our JavaScript code in the frontend through eslint_ to ensure
 that new code has a consistent style and doesn't suffer from common
 errors. Before submitting a patch, check that your code passes these tests.
 
-* If you haven't already done so, install local dependencies by running ``npm install`` from the project root.
-* Run ``npm run lint``.
+* If you haven't already done so, install local dependencies by running ``yarn install --no-bin-links`` from the project root.
+* Run ``yarn run lint``.
 
 .. _eslint: http://eslint.org/
 
@@ -63,11 +63,12 @@ Running the unit tests
 
 The unit tests for the UI are run with Karma_. To do this:
 
-* If you haven't already done so, install local dependencies by running ``npm install`` from the project root.
-* Run ``npm test``.
+* If you haven't already done so, install local dependencies by running ``yarn install --no-bin-links`` from the project root.
+* Run ``yarn test``.
 
 
 .. _Karma: http://karma-runner.github.io/0.8/config/configuration-file.html
 .. _treeherder repo: https://github.com/mozilla/treeherder
-.. _Node.js: http://nodejs.org/download/
+.. _Node.js: https://nodejs.org/en/download/current/
+.. _Yarn: https://yarnpkg.com/en/docs/install
 

puppet/files/treeherder/.profile

@@ -10,6 +10,8 @@ cd "$HOME/treeherder"
 
 # Helper aliases
 
+alias npm='echo "Please use yarn instead of npm to ensure yarn.lock stays in sync!"'
+
 function thelp {
     echo "
     Treeherder-specific helpful aliases: