Skip to content

Latest commit

 

History

History
213 lines (141 loc) · 11.8 KB

README.md

File metadata and controls

213 lines (141 loc) · 11.8 KB
Raw

Tidepool Uploader

Greenkeeper badge

CircleCI Build status

This is an Electron App that acts as an uploader client for Tidepool. It is intended to allow you to plug diabetes devices into your computer's USB port, read the data stored on them, and upload a standardized version of the data to the Tidepool cloud.

This README is focused on just the details of getting the uploader running locally. For more detailed information aimed at those working on the development of the uploader, please see the developer guide.

Table of contents

How to set it up

  1. Clone this repository.
  2. Make sure you have node v8.x installed. If you are managing node installations with nvm, which we highly recommend, you can just do nvm use when navigating to this repository to switch to the correct version of node. (In this repository, the correct version of node will always be the version of node packaged by the version of Electron that we are using and specified in the .nvmrc file.)
  3. Run npm install or, preferably, yarn
  4. Set the config for the environment you want to target (see Config below)
  5. Run the following command:
$ npm run dev

or

$ yarn dev

(This will bundle the application with webpack and watch for changes. When it stops printing output you can continue to the next step.)

NB: React components and CSS will hot load after changes (this can be confirmed by watching the JavaScript console), but changes to device drivers and other code outside of the React components will not - use 'Reload' to reload after such changes. If the compilation/hot reload of a component fails for any reason (e.g. from a syntax error) you may need to reinitialize the hot loader by reloading the application.

Config

Configuration values (for example the URL of the Tidepool Platform) are set via environment variables. If you need to add a config value, modify the .config.js file. If you need to read a config value inside the app, use var config = require('./lib/config'). To set config values (do this before building the app), you can use Shell scripts that export environment variables (see config/local.sh for an example that exports the appropriate variables when running the whole Tidepool platform locally using runservers), for example:

$ source config/local.sh
$ yarn start

Debug Mode(s)

For ease of development we have several debug features that developers can turn on and off at will (and to suit various development use cases, such as working on a new device driver versus working on the app's UI). Each of these debug features is set with an environment variable, but rather than being loaded through .config.js (as we do for production configuration variables, see above), we load these through the webpack DefinePlugin (see Pete Hunt's webpack-howto for an example, although note Hunt uses the term 'feature flag').

DEBUG_ERROR

The environment variable DEBUG_ERROR (boolean) controls whether or not errors sourced in device drivers are caught and an error message displayed in the UI (the production setting) or whether they are thrown in the console (much more useful for local development because then the file name and line number of the error are easily accessible, along with a stack trace). DEBUG_ERROR mode is turned on by default in config/device-debug.sh.

This can also be toggled internally in the running Electron app via a right-click context menu available on the login screen, much like the menu for switching environments.

Local Development w/o Debug Mode(s)

All debug options are turned off by default in config/local.sh.

Tests

To run the tests in this repository as they are run on CircleCI and Appveyor use:

$ yarn test

or

$ yarn test

Linting & Code Style

We use ESLint to lint our JavaScript code. We try to use the same linting options across all our client apps, but there are a few exceptions in this application, noted with comments in the .eslintrc configuration file.

To run the linter (which also runs on CircleCI and Appveyor with every push, along with npm test), use:

$ npm run lint

Aside from the (fairly minimal) JavaScript code style options we enforce through the linter, we ask that internal developers and external contributors try to match the style of the code in each module being modified. New modules should look to similar modules for style guidance. In React component code, use existing ES6/ES2015 components (not legacy ES5 components) as the style model for new components.

NB: Please keep ES5 and ES6/ES2015 code distinct. Do NOT use ES6/ES2105 features in ES5 modules (most easily recognizable by the use of require rather than import).

Docs

Docs reside in several places in this repository, such as docs/ and lib/drivers/docs. They are built as a static site with GitBook and served at developer.tidepool.org via GitHub Pages.

See this guidance on our use of GitBook at Tidepool.

Publishing

This section is Tidepool-specific. Release management and application updates are handled via the Github provider in the electron-builder project. The recommended workflow for a new production release is as follows:

  1. When you're working on what might become a new release, increment the version number in package.json and app/package.json and commit/push (on the branch)
  2. The CI server(s) will create a draft release in Github with the title of the version from the package.json file and will automatically attach the distribution artifacts to that draft (drafts are not publicly visible)
  3. When your pull request is approved and merged to master, go to the draft release and type in the version for the tag name, ensure that you're targeting the master branch, fill out the release notes and publish the release. This will create the tag for you.

For a non-production release (alpha, dev, etc.)

  1. Increment the version number in package.json and app/package.json and ensure that you have included the channel information after the version patch number (i.e. v0.304.0-alpha or v0.304.0-beta.2). The hyphen separated version semantic is important.
  2. The CI server(s) will create a draft release in Github with the title of the version from the package.json file and will automatically attach the distribution artifacts to that draft (drafts are not publicly visible)
  3. When you want to publish your non-production release, go to your draft and type in the version for the tag name, ensure that you're targeting the branch that you're currently releasing from, mark the release as a pre-release, fill out the release notes and publish the release. This will create the tag for you on the branch that you want.

The Uploader has a self-update mechanism that will look at the latest release and compare versions, downloading and prompting the user to update if a newer version is available. For production releases, only official releases will be considered. For non-production releases (-alpha, -beta.2, etc.) releases marked as pre-release will also be checked, matching against the string portion of the post-hyphen version segment. For more detail about this behavior see the electron-builder docs concerning auto-update options

Editor Configuration

Atom

apm install editorconfig es6-javascript javascript-snippets linter linter-eslint language-babel autocomplete-modules file-icons

Sublime

Others

DevTools

Toggle Chrome DevTools

  • OS X: Cmd Alt I or F12
  • Linux: Ctrl Shift I or F12
  • Windows: Ctrl Shift I or F12

See electron-debug for more information.

DevTools extension

This project includes the following DevTools extensions:

You can find the tabs on Chrome DevTools.

If you want to update extensions version, please set UPGRADE_EXTENSIONS env, just run:

$ UPGRADE_EXTENSIONS=1 npm run dev

# For Windows
$ set UPGRADE_EXTENSIONS=1 && npm run dev

CSS Modules

All .module.less files will be use css-modules.

Packaging

To package apps for the local platform:

$ npm run package
$ yarn package

To package apps with options:

$ npm run package -- --[option]

To package the app on your local machine, you need to set the ROLLBAR_POST_TOKEN environment variable to send telemetry data to Rollbar. You can get one for free from https://rollbar.com

macOS: To notarize the app so that it will run on macOS Mojave, you need to set the environment variables APPLEID and APPLEIDPASS. Note that you need to set an app-specific password in https://appleid.apple.com for this to work.

Further commands

To run the application without packaging run

$ npm run build
$ npm start

To run End-to-End Test

$ npm run build
$ npm run test-e2e

Options

See electron-builder CLI Usage

Module Structure

This project uses a two package.json structure.

  1. If the module is native to a platform or otherwise should be included with the published package (i.e. bcrypt, openbci), it should be listed under dependencies in ./app/package.json.
  2. If a module is imported by another module, include it in dependencies in ./package.json. See this ESLint rule.
  3. Otherwise, modules used for building, testing and debugging should be included in devDependencies in ./package.json.