Contributing

If you'd like to help but can't code, we could definitely use some help documenting features!

If you'd like to make a contribution to the MicrobeTrace code base, please review the CDC's Contribution Guidelines.

Architecture

MicrobeTrace is a desktop application (targeting Windows), based off of the Electron Boilerplate template.

Requirements

To develop, you're going to need a computer with:

• git
• node and npm
• yarn (optional, but preferred)

Getting Started

To jump right to development, Fork the repository. Once Github finishes, open up your terminal emulator, cd over to your favorite projects directory, and clone your fork of the repository. i.e., run

git clone https://github.com/<your-github-username>/MicrobeTRACE.git

This will download this repo. Next, enter the repository:

cd MicrobeTrace

... and install the dependencies:

yarn install

(Alternately, if you didn't follow my advice and install yarn, run this:)

npm install

This will download all of the development dependencies for this project. Note that this will download several hundred megabytes. Luckily, the dev dependencies are much, much larger than the prod dependencies, so the distribution file that should be output will only take up a few tens of megabytes.

Next, issue the following command to your command prompt:

npm start

This will launch the developer's view of the application itself. It includes real-time recompilation of the frontend scripts, but not real-time refreshing, so every time you change something you'll probably need to give the application focus and then hit Ctrl-R to test the change.

What to touch, what not to

At this point, there are only a handful of files that should need editing.

• app/
  • views/*.html
  • workers/*.html
  • stylesheets/main.css
  • index.html
• src/
  • app.js
  • background.js

NOTE: app/app.js and app/background.js are dynamically generated and not stored in the repository, so any changes to these files will not result in viable commits. Please edit src/app.js and src/background.js instead.

Basically, anything that's listed in the .gitignore file shouldn't be messed with. These are either dependencies that you should download and ignore (e.g. node_modules/), or compiled versions (e.g. app/app.js or app/background.js) of files that are designed to be edited (e.g. src/app.js)

Edit these files as needed to create the desired changes, and test the changes.

NOTE: Any changes you make will be available after you refresh the application (F5), except for changes to src/background.js. Those require a hard relaunch (Ctrl-C followed by another npm run).

Once you've gotten the desired changes, commit your edits, push them upstream, and submit a pull request.

What's screwed up and (probably) fixable

Full disclosure: This project does not adhere to anything close to a set of best-practices. If you're interested in paying down some technical debt, here are some good places to start.

1. The Data Architecture - This is a biggie. Right now, this project is mostly powered by jQuery spaghetti. It works if you (the developer) catch all the edge cases, but there are a lot of things that can go wrong. What we should do is implement some sort of MV* framework. I may start moving toward using React, time-permitting.
2. The UI - One of the requirements was to show multiple views of the data on the same monitor at the same time, such that a user can interact with one view and see the effects on a different view. Rather than use a clever solution, Eric just spun the different views off into separate windows. There are a bunch of things wrong with this, but foremost is that we then need to use IPC, which sucks. It also makes this issue intimately tied in with items 1, above. If you're ambitious, tackle both at once, and you'll have a much, much better codebase (and ultimately, product).

Other stuff

There is one especially odd dependency I should mention: tn93.js. This is a javascript port I (Tony Boyles) wrote of libtn93, itself a C port of TN93 implementation used in the original HIVTrace. An earlier version of this project used hivtrace along with NetworkX to compute a bounded minimum spanning tree of tn93 distances. Unfortunately, this architecture proved much too slow and heavy to ship with a viable product. The javascript alternative has its downsides (most conspicuously, Electron's hacks around Node's single-threadedness make either writing asynchronous code a headache, or dooms the user to waiting around a bunch, but usually both). However, the Javascript solution is comparatively quick (given that it's performing an O(n^2) operation and there's literally nothing we can do about that).

Anyway, I've maintained tn93.js in a separate, CDC repository. Contact me if you need/want to make changes or optimizations to it.