Skip to content

Developer Workflow

Jump to bottom
Daniel Weck edited this page Aug 9, 2019 · 14 revisions

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

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. 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.

Localization (Translations)

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

Clone this wiki locally