Skip to content

Development workflow and tools

Jump to bottom
romainAA edited this page Aug 22, 2018 · 13 revisions

Pre-requisites

Because of the complex directory structure, and scripts relying on bash etc, it might be difficult to get the development environment configured on Windows. In that case, we recommend a virtual machine with Ubuntu. Scripts are tested on both MacOS and Linux.

Getting started

Make sure you have node and meteor installed, check out the github repo, run ./initial_setup.sh, go to ./frog, and run meteor.

Error messages

Note that the following is expected and does not represent a problem

Unable to resolve some modules:

  "bufferutil" in /Users/stian/src/FROG/frog/node_modules/ws/lib/BufferUtil.js (os.osx.x86_64)
  "utf-8-validate" in /Users/stian/src/FROG/frog/node_modules/ws/lib/Validation.js (os.osx.x86_64)
  "hiredis" in /Users/stian/src/FROG/frog/node_modules/redis-parser/lib/hiredis.js (os.osx.x86_64)

Repository structure

The repository is fairly complex, but we try to supply a number of tools to make it easier to work with.

The main FROG program is in ./frog, and is a Meteor package. It is run by typing meteor once in that directory. This starts the meteor development server, which watches all files (including symlinked node modules) and automatically reloads on change. It includes Babel and all other build-steps that would otherwise be done by Webpack (these only apply to files in ./frog, not dependencies).

All activities are independent npm packages, and are found in the ./ac directory. Their directory names and package ids should be prefixed with ac-. They should all correspond to the ActivityPackageT type definition.

All operators are independent npm packages, and are found in the ./op directory. Their directory names and package ids should be prefixed with op-. All operators should correspond to either the productOperatorT or socialOperatorT type definitions.

frog-utils contains shared type definitions and useful functions. It is the only package that is available to all other packages (both ./frog, and ./ac/*, ./op/*), so any functionality shared between multiple packages should be placed there.

Adding/changing dependencies

To make the mono-repo structure easier to work with, we are using the workspaces functionality of yarn. This functionality is very new, and still has some problems with Meteor. When trying to add a dependency to a package, the safest way is to manually add the dependency to package.json of the relevant package, and then run npm start yarn.

If anything wrong happens, from the repository root, run:

git clean -fdx; ./initial_setup.sh

Note that this will remove all untracked files - either commit them temporarily or git stash them. It will also reset the Mongo Collections and hence all graphs and activities that were not sent to the cloud library will be lost.

If you still have problems, you can try

killall -9 node

and then restart meteor. The final thing to try is meteor reset in the ./frog directory. Note that this will also reset the Mongo database.

Adding a new operator/activity

To add a new operator or activity, use the script createPackage.js in the following way:

node createPackage.js [activity|operator] id name

for example

node createPackage.js activity ac-video 'Video player'

This will create a new directory ./ac/ac-video, populated based on a template minimalistic activity/operator, and link the activity/operator into FROG. Follow the instructions emitted by the tool to prepare the repository for further work.

Other tools/scripts

For continuous integration, we use a Dockerfile. To maximize caching, this is a fairly complex file, but it is automatically generated by create-Dockerfile.sh, so nothing manual should need to be added to this. If you are developing on a fork of FROG, we can add your repository to our locally hosted CI for free, contact us.

We use nps and ./package-scripts.js for what would typically be scripts in package.json in the root directory, to run these, type npm start <script>, instead of npm run. Type npm start help for a list of the commands:

   FROG scripts:

test - run all tests
eslint - run ESLint
eslint.fix - run ESLint --fix, will format with Prettier
flow - run Flow
flow.quiet - run Flow --quiet
jest - run Jest
jest.watch - run Jest in watch mode
setup - run initial setup
setup.clean - clean all files (will delete files not added to Git) and run setup
server - run server (can be run from any directory)
build - build current directory
build.all - build all directories

In the browser

  • Install and use React Dev Tools (video)
Clone this wiki locally