Update scripts and docs to use yarn where appropriate

Most `npm` operations are replaced with `yarn`, which generally has better
behavior. However, steps like publish that write to the NPM registry are left to
`npm`, which currently handles these tasks best.

Author: jryans

.gitignore

@@ -12,6 +12,6 @@ reports
 /lib
 /specbuild
 
-# version file and tarball created by 'npm pack'
+# version file and tarball created by `npm pack` / `yarn pack`
 /git-revision.txt
 /matrix-js-sdk-*.tgz

README.md

@@ -21,7 +21,9 @@ Please check [the working browser example](examples/browser) for more informatio
 In Node.js
 ----------
 
-``npm install matrix-js-sdk``
+Using `yarn` instead of `npm` is recommended. Please see the Yarn [install guide](https://yarnpkg.com/docs/install/) if you do not have it already.
+
+``yarn add matrix-js-sdk``
 
 ```javascript
   var sdk = require("matrix-js-sdk");
@@ -283,7 +285,7 @@ This SDK uses JSDoc3 style comments. You can manually build and
 host the API reference from the source files like this:
 
 ```
-  $ npm run gendoc
+  $ yarn gendoc
   $ cd .jsdoc
   $ python -m SimpleHTTPServer 8005
 ```
@@ -319,15 +321,15 @@ To provide the Olm library in a browser application:
 
 To provide the Olm library in a node.js application:
 
- * ``npm install https://matrix.org/packages/npm/olm/olm-3.0.0.tgz``
+ * ``yarn add https://matrix.org/packages/npm/olm/olm-3.0.0.tgz``
    (replace the URL with the latest version you want to use from
     https://matrix.org/packages/npm/olm/)
  * ``global.Olm = require('olm');`` *before* loading ``matrix-js-sdk``.
 
-If you want to package Olm as dependency for your node.js application, you
-can use ``npm install https://matrix.org/packages/npm/olm/olm-3.0.0.tgz
---save-optional`` (if your application also works without e2e crypto enabled)
-or ``--save`` (if it doesn't) to do so.
+If you want to package Olm as dependency for your node.js application, you can
+use ``yarn add https://matrix.org/packages/npm/olm/olm-3.0.0.tgz``. If your
+application also works without e2e crypto enabled, add ``--optional`` to mark it
+as an optional dependency.
 
 
 Contributing
@@ -337,28 +339,28 @@ want to use this SDK, skip this section.*
 
 First, you need to pull in the right build tools:
 ```
- $ npm install
+ $ yarn install
 ```
 
 Building
 --------
 
 To build a browser version from scratch when developing::
 ```
- $ npm run build
+ $ yarn build
 ```
 
 To constantly do builds when files are modified (using ``watchify``)::
 ```
- $ npm run watch
+ $ yarn watch
 ```
 
 To run tests (Jasmine)::
 ```
- $ npm test
+ $ yarn test
 ```
 
 To run linting:
 ```
- $ npm run lint
+ $ yarn lint
 ```

git-hooks/pre-commit

@@ -21,4 +21,4 @@ export PATH="$rootdir/node_modules/.bin:$PATH"
 
 # now run our checks
 cd "$tmpdir"
-npm run lint
+yarn lint

jenkins.sh

@@ -6,7 +6,7 @@ export NVM_DIR="$HOME/.nvm"
 [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
 
 nvm use 10 || exit $?
-npm install || exit $?
+yarn install || exit $?
 
 RC=0
 
@@ -18,17 +18,19 @@ function fail {
 # don't use last time's test reports
 rm -rf reports coverage || exit $?
 
-npm test || fail "npm test finished with return code $?"
+yarn test || fail "yarn test finished with return code $?"
 
-npm run -s lint -- -f checkstyle > eslint.xml ||
+yarn -s lint -f checkstyle > eslint.xml ||
     fail "eslint finished with return code $?"
 
 # delete the old tarball, if it exists
 rm -f matrix-js-sdk-*.tgz
 
-npm pack ||
-    fail "npm pack finished with return code $?"
+# `yarn pack` doesn't seem to run scripts, however that seems okay here as we
+# just built as part of `install` above.
+yarn pack ||
+    fail "yarn pack finished with return code $?"
 
-npm run gendoc || fail "JSDoc failed with code $?"
+yarn gendoc || fail "JSDoc failed with code $?"
 
 exit $RC

package.json

@@ -7,18 +7,18 @@
     "test:build": "babel -s -d specbuild spec",
     "test:run": "istanbul cover --report text --report cobertura --config .istanbul.yml -i \"lib/**/*.js\" node_modules/mocha/bin/_mocha -- --recursive specbuild --colors --reporter mocha-jenkins-reporter --reporter-options junit_report_path=reports/test-results.xml",
     "test:watch": "mocha --watch --compilers js:babel-core/register --recursive spec --colors",
-    "test": "npm run test:build && npm run test:run",
-    "check": "npm run test:build && _mocha --recursive specbuild --colors",
+    "test": "yarn test:build && yarn test:run",
+    "check": "yarn test:build && _mocha --recursive specbuild --colors",
     "gendoc": "babel --no-babelrc -d .jsdocbuild src && jsdoc -r .jsdocbuild -P package.json -R README.md -d .jsdoc",
-    "start": "npm run start:init && npm run start:watch",
+    "start": "yarn start:init && yarn start:watch",
     "start:watch": "babel -s -w --skip-initial-build -d lib src",
     "start:init": "babel -s -d lib src",
     "clean": "rimraf lib dist",
     "build": "babel -s -d lib src && rimraf dist && mkdir dist && browserify -d browser-index.js | exorcist dist/browser-matrix.js.map > dist/browser-matrix.js && uglifyjs -c -m -o dist/browser-matrix.min.js --source-map dist/browser-matrix.min.js.map --in-source-map dist/browser-matrix.js.map dist/browser-matrix.js",
-    "dist": "npm run build",
+    "dist": "yarn build",
     "watch": "watchify -d browser-index.js -o 'exorcist dist/browser-matrix.js.map > dist/browser-matrix.js' -v",
     "lint": "eslint --max-warnings 101 src spec",
-    "prepublish": "npm run clean && npm run build && git rev-parse HEAD > git-revision.txt"
+    "prepare": "yarn clean && yarn build && git rev-parse HEAD > git-revision.txt"
   },
   "repository": {
     "type": "git",

release.sh

@@ -6,7 +6,9 @@
 #   github-changelog-generator; install via:
 #     pip install git+https://github.com/matrix-org/github-changelog-generator.git
 #   jq; install from your distribution's package manager (https://stedolan.github.io/jq/)
-#   hub; install via brew (OSX) or source/pre-compiled binaries (debian) (https://github.com/github/hub) - Tested on v2.2.9
+#   hub; install via brew (macOS) or source/pre-compiled binaries (debian) (https://github.com/github/hub) - Tested on v2.2.9
+#   npm; typically installed by Node.js
+#   yarn; install via brew (macOS) or similar (https://yarnpkg.com/docs/install/)
 
 set -e
 
@@ -22,6 +24,8 @@ else
     echo "hub is required: please install it"
     exit
 fi
+npm --version > /dev/null || (echo "npm is required: please install it"; kill $$)
+yarn --version > /dev/null || (echo "yarn is required: please install it"; kill $$)
 
 USAGE="$0 [-xz] [-c changelog_file] vX.Y.Z"
 
@@ -88,6 +92,8 @@ if [ -z "$skip_changelog" ]; then
     update_changelog -h > /dev/null || (echo "github-changelog-generator is required: please install it"; exit)
 fi
 
+# Login and publish continues to use `npm`, as it seems to have more clearly
+# defined options and semantics than `yarn` for writing to the registry.
 actual_npm_user=`npm whoami`;
 if [ $expected_npm_user != $actual_npm_user ]; then
     echo "you need to be logged into npm as $expected_npm_user, but you are logged in as $actual_npm_user" >&2
@@ -147,18 +153,18 @@ cat "${changelog_file}" | `dirname $0`/scripts/changelog_head.py > "${latest_cha
 set -x
 
 # Bump package.json and build the dist
-echo "npm version"
-# npm version will automatically commit its modification
+echo "yarn version"
+# yarn version will automatically commit its modification
 # and make a release tag. We don't want it to create the tag
 # because it can only sign with the default key, but we can
 # only turn off both of these behaviours, so we have to
 # manually commit the result.
-npm version --no-git-tag-version "$release"
+yarn version --no-git-tag-version "$release"
 
-# commit package-lock.json if it exists, is versioned, and is modified
-if [[ -f package-lock.json && `git status --porcelain package-lock.json | grep '^ M'` ]];
+# commit yarn.lock if it exists, is versioned, and is modified
+if [[ -f yarn.lock && `git status --porcelain yarn.lock | grep '^ M'` ]];
 then
-    pkglock='package-lock.json'
+    pkglock='yarn.lock'
 else
     pkglock=''
 fi
@@ -178,7 +184,7 @@ fi
 # assets.
 # We make a completely separate checkout to be sure
 # we're using released versions of the dependencies
-# (rather than whatever we're pulling in from npm link)
+# (rather than whatever we're pulling in from yarn link)
 assets=''
 dodist=0
 jq -e .scripts.dist package.json 2> /dev/null || dodist=$?
@@ -189,10 +195,10 @@ if [ $dodist -eq 0 ]; then
     pushd "$builddir"
     git clone "$projdir" .
     git checkout "$rel_branch"
-    npm install
+    yarn install
     # We haven't tagged yet, so tell the dist script what version
     # it's building
-    DIST_VERSION="$tag" npm run dist
+    DIST_VERSION="$tag" yarn dist
 
     popd
 
@@ -281,12 +287,13 @@ fi
 rm "${release_text}"
 rm "${latest_changes}"
 
-# publish to npmjs
+# Login and publish continues to use `npm`, as it seems to have more clearly
+# defined options and semantics than `yarn` for writing to the registry.
 npm publish
 
 if [ -z "$skip_jsdoc" ]; then
     echo "generating jsdocs"
-    npm run gendoc
+    yarn gendoc
 
     echo "copying jsdocs to gh-pages branch"
     git checkout gh-pages
@@ -311,7 +318,7 @@ git checkout master
 git pull
 git merge "$rel_branch"
 
-# push master  and docs (if generated) to github
+# push master and docs (if generated) to github
 git push origin master
 if [ -z "$skip_jsdoc" ]; then
     git push origin gh-pages

travis.sh

@@ -2,12 +2,15 @@
 
 set -ex
 
-npm run lint
+yarn lint
 
 # install Olm so that we can run the crypto tests.
-npm install https://matrix.org/packages/npm/olm/olm-3.1.0-pre1.tgz
+# This will add Olm as dependency, since it's currently unlisted.
+# (`yarn` does not have an install dependency without adding mode.)
+# TODO: Should Olm be a listed dev dependency instead, so that we can have it for testing
+# and don't need to run an extra step here?
+yarn add https://matrix.org/packages/npm/olm/olm-3.1.0-pre1.tgz
 
-npm run test
-
-npm run gendoc
+yarn test
 
+yarn gendoc