Skip to content

Latest commit

 

History

History
203 lines (157 loc) · 15.4 KB

Developers.md

File metadata and controls

203 lines (157 loc) · 15.4 KB
Raw

Developers

Pre-requisites

Developing UD-Viz applications requires some knowledge about :

Development Tips

Use nvm to manage the npm versions

Developers are advised to use node version manager (nvm). nvm allows you to quickly install and use different versions of node via the command line.

To download and install follow this link: https://github.com/nvm-sh/nvm#installing-and-updating

Tips for the VisualStudio Code IDE

When using Visual Studio Code, you can install the following extentions to make your life easier:

Tips for Windows developers

As configured, the coding style requires a Linux style newline characters which might be overwritten in Windows environments (both by git and/or your editor) to become CRLF. When such changes happen eslint will warn about "incorrect" newline characters (which can always be fixed with npm run eslint-fix but this process quickly gets painful). In order to avoid such difficulties, the recommended pratice consists in

  1. setting git's core.autocrlf to false (e.g. with git config --global core.autocrlf false)
  2. configure your editor/IDE to use Unix-style endings
  3. In order to use scripts that launch a shell script with Powershell: npm config set script-shell "C:\\Program Files\\git\\bin\\bash.exe"

Npm Scripts

The npm package.json file defines a set of scripts whose respective purpose are quickly documented here

Script Description
npm run clean Remove files and folders generated by npm install and the npm run build-(dev-)examples script such as ./node_modules, package-lock.json, and ./dist
npm run clear-node Linux Command: Kill all node process (this is a sudo script)
npm run reset Reinstalls npm dependencies. This script runs npm run clean and npm install command
npm run build-examples Build a production bundle base on this webpack config
npm run build-dev-examples Build a development bundle base on this webpack config
npm run dev-examples Launch a watcher running this script. See here for more information
npm run eslint Run the linter. See here for more information
npm run eslint-quiet Run the linter without displaying warnings, only errors
npm run eslint-fix Run the linter and attempt to fix errors and warning automatically
npm run test-unit Build examples bundle if needed and run npm run test in each packages . Also ran by CI. See here for more information
npm run test-functional Build examples bundle if needed and run each *.html in ./examples folder . Also ran by CI. See here for more information
npm run test-links Run this script to detect dead links in markdown. Also ran by CI. See here for more information
npm run local-ci Run CI on your local computer. See here for more information
npm run pre-publish Change version in all package.json ( eg npm run pre-publish x.x.x ). See this script
npm run docs Delete old docs and run this script which generate docs
npm run dev-docs Launch a watcher for generating and debugging the documentation. See here for more information
npm run back-end run an http server (with some string-replace) + a game socket service.
http://locahost:8000/
npm run analyze-bundle Use webpack-bundle-analyzer to see what's inside the examples bundle
npm run analyze-dev-bundle Use webpack-bundle-analyzer to see what's inside the examples dev bundle
npm run start Run npm run build-examples and npm run back-end

Some comments about selected package.json scripts

Consider the dev-examples script

cross-env NODE_ENV=development nodemon --signal SIGKILL --trace-warnings --verbose [--watch ./packages/PACKAGE_NAME]  --delay 2500ms ./bin/devExamples.js -e js,css

This script builds on

  • cross-env NODE_ENV=development: cross-env package will allows to add variable in command line (here NODE_ENV) to process.env. See cross-env, process.env.
  • nodemon [--options] ./bin/devExamples.js: nodemon is a node provided development oriented tool. Its purpose is to automatically restart the interpretation of a set of javascript files (here bin/devExamples.js) when one those files changes (e.g. was edited).

We can now dive into bin/devExamples.js where

  • exec and spawn are two functions from child-process-promise which allows to execute node script. See Promise doc.
  • exec('npm run build-dev-examples'):
    • cross-env NODE_ENV=development webpack --config=./webpack.config.js: webpack is the tool it permits to create a bundle of your code. The config is defined in ./webpack.config.json. See doc here.
  • const child = spawn('cross-env NODE_ENV=development node', ['./bin/backEnd.js'], { shell: true, });: Interprets bin/backEnd.js that launches an express server.

Debugging the examples

npm run dev-examples

Develop with modified ud-viz library in your demo

When developing an application that uses UD-Viz as library, you might need to propose modifications/fixes/improvements of UD-Viz. In doing so you will need a set up that allows for simultaneously modifying both codes (the one of your application and the one of UD-Viz) in order to co-evolve UD-Viz and its usage within your application.

In order to establish that specific developing context you might

  • clone both repositories side by side (that is your cloned application repository stands in the same directory as the cloned UD-Viz) on your local
  • within the cloned UD-Viz repository, run npm install (because your webpack.config.js will make reference to ../UD-Viz/node_modules).
  • Modify your the package.json of your application in order to "point" to the cloned version of the UD-Viz library. Entries of the form 
    "dependencies": {
   "@ud-viz/*": "x.x.x"
}
    should replaced with 
    "dependencies": {
  "@ud-viz/*": "file:../UD-Viz/packages/*"
}
    where the path is a relative path from the package.json to your cloned version of the UD-Viz library. Notice that you should only modify the paths to the UD-Viz npm (sub-)packages that you wish to adapt.
  • Reinstall ud-viz npm packages 
    rm -f -r node_modules && rm -f package-lock.json && npm i
  • Eventually you have to modify the webpack.config.js in order to indicate to webpack what directories should be searched when resolving modules the UD-Viz's 'node_modules' folder: 
    module.exports = {
  //...
  resolve: {
    modules: ['../UD-Viz/node_modules', './node_modules'],
  },
};
    It is important to add the '../UD-Viz/node_modules' in first position of the array.

When you application uses code watchers (e.g. nodemon) on automatic rebuild purposes, the code watchers will be blind to changes operated in the ../UD-Viz/ file hierarchy.

Continuous Integration (Travis CI)

Each time origin/master branch is impacted by changes, Travis CI is triggered. It does a set of jobs describe in travis.yml.

Jobs list :

  • npm run eslint: Lint code sources
  • npm run test-unit: Unit test
  • npm run test-functional: Functional test
  • npm audit --audit-level=low: Npm native command (npm-audit) which check packages dependencies vulnerabilities.
  • npm run test-links: Run this script which check if links are not broken.
  • node ./test/docs.js: Run this script which check if documentation is generated without warning or error.

Contributing

For information on the accepted coding style, submitting Issues, and submitting Pull Requests see Contributing.md

Publishing

For creating a new release see ReleasePublish.md

Generating the documentation

The Online documentation can be re-generated by following these instructions.