Developer Workflow

Ace App (ace-gui)

Note that a special branch and build system is required to integrate the Ace core components (i.e. this ace mono-repository) into the Ace App project (ace-gui repository). Please visit this dedicated wiki page to learn more.

Prerequisites

• NodeJS and NPM
• Yarn

Initial Setup

• cd MY_ACE_FOLDER (choose your folder name / filesystem location)
• git clone https://github.com/daisy/ace.git
• cd ace
• git checkout master (or any other suitable branch)
• yarn clean-node-modules or rm -rf node_modules && rm -rf packages/*/node_modules (this is really only needed if yarn install was already invoked)
• yarn clean-libs or rm -rf packages/*/lib (this is really only needed if yarn build was already invoked)
• rm yarn.lock (advanced step: this is not normally necessary, and should only be used to upgrade NPM dependencies, use with caution!)
• yarn cache clean (this step is optional, only necessary if the package cache is causing issues)
• yarn install (this will automatically invoke yarn build)
• git status && git --no-pager diff (advanced step: this should show yarn.lock changes if rm yarn.lock was previously called)

Unit Tests

• yarn test

Additional commands introduced in this Pull Request:

• yarn test-cli
• yarn test-electron
• yarn test-electron-cli

Build, Run

• yarn build: invoke this script any time the source code is modified, in order to ensure the lib subfolders of each Ace package are re-generated.
• yarn watch: launch this script to automatically trigger the build step when code changes are detected.
• node packages/ace-cli/bin/ace.js -V -f -o "PATH_TO_OUTPUT_FOLDER" "PATH_TO_EPUB_FILE": this is just an example of how to run the locally-built Ace CLI.

Additional commands introduced in this Pull Request:

• node node_modules/electron/cli.js ./packages/ace-axe-runner-electron/lib/cli.js -V -f -o "PATH_TO_OUTPUT_FOLDER" "PATH_TO_EPUB_FILE": this is just an example of how to run the locally-built Ace CLI, via the Electron-based Axe runner (which is used by the Ace App / ace-gui) instead of the Puppeteer-based one (which is used by the Ace CLI).
• ./compareAxeRunners.sh "PATH_TO_EPUB_FILE": this shell script invokes the Puppeteer-based Axe runner, followed by the Electron-based one. The script displays performance / timing information, and shows any differences in the generated report.json (there shouldn't be any other than the date/time of the evaluation).

Dependency Maintenance

• ncu is recommended to discover out of date NPM packages, and to subsequently yarn upgrade or rm -rf node_modules && rm yarn.lock && yarn install (which, in both cases, will update yarn.lock to match frozen versions of the latest available and approved dependencies). Use -x @types/node to skip specific comma-separated packages. Here is a handy ncu.sh shell script to check each package in the mono-repository:

#!/bin/bash

for relativefilepath in packages/*; do
    filename=`basename "${relativefilepath}"`
    echo "${filename} (${relativefilepath})"
    cd "${relativefilepath}"
    ncu
    cd - &> /dev/null
done

• npm-check is a useful alternative / complement to ncu. Use --ignore @types/node to skip specific packages. Use npm-check --skip-unused --no-emoji for cleaner shell output.
• david is a useful alternative / complement to ncu. The online service can be helpful too: https://david-dm.org/daisy/ace?type=dev
• yarn outdated / npm outdated also helps :)

Additional method introduced in this Pull Request:

• package.json contains a non-standard innerPackageDependencies JSON property which lists every NPM packages used by @daisy sub-packages in the ace mono-repository. When temporary renamed to dependencies, this allows ncu to check the entire dependency tree for updates.
• The aforementioned convenient ncu.sh shell script is included in this PR / branch.

Localization (Translations)

Please visit this dedicated wiki page to learn more about how language resources are created and maintained.