From 2144791d5274c531ebfcc95184df79eeae0349ca Mon Sep 17 00:00:00 2001 From: "J. Ryan Stinnett" Date: Fri, 8 Mar 2019 15:45:57 +0000 Subject: [PATCH] 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. --- .gitignore | 2 +- README.md | 26 ++++++++++++++------------ git-hooks/pre-commit | 2 +- jenkins.sh | 14 ++++++++------ package.json | 10 +++++----- release.sh | 33 ++++++++++++++++++++------------- travis.sh | 13 ++++++++----- 7 files changed, 57 insertions(+), 43 deletions(-) diff --git a/.gitignore b/.gitignore index 93fb23d2e..a3bb80f4d 100644 --- a/.gitignore +++ b/.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 diff --git a/README.md b/README.md index be2fa0f86..d02a9740a 100644 --- a/README.md +++ b/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,7 +339,7 @@ want to use this SDK, skip this section.* First, you need to pull in the right build tools: ``` - $ npm install + $ yarn install ``` Building @@ -345,20 +347,20 @@ 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 ``` diff --git a/git-hooks/pre-commit b/git-hooks/pre-commit index 2bb0e2cad..b6988ae7a 100755 --- a/git-hooks/pre-commit +++ b/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 diff --git a/jenkins.sh b/jenkins.sh index 87a1137b3..eb4543936 100755 --- a/jenkins.sh +++ b/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 diff --git a/package.json b/package.json index 594cad32b..f8cf0a61a 100644 --- a/package.json +++ b/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", diff --git a/release.sh b/release.sh index b639bb670..9f06e5033 100755 --- a/release.sh +++ b/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 diff --git a/travis.sh b/travis.sh index 02b2f0bbb..84bb9462d 100755 --- a/travis.sh +++ b/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