How to develop Enketo Core
- install prerequisites:
- Volta (optional, but recommended)
- Node.js 16 and npm 6 (Node.js 14 is also supported)
- grunt-cli
- install dependencies with
npm install
- build with
grunt
(npx grunt
) - start built-in auto-reloading development server with
npm start
- browse to http://localhost:8005 and load an XForm url with the
xform
queryparameter or load a local from the /tests/forms folder in this repo - run tests with
npm test
(headless chrome) andnpm run test-browsers
(browsers); note: running tests updates the coverage badge in README.md, but these changes should not be committed except when preparing a release - adding the querystring
touch=true
and reducing the window size allows you to simulate mobile touchscreens
Notes for JavaScript Developers
- When creating new functions/Classes, make sure to describe them with JSDoc comments.
- JavaScript style see ESLint config files. The check is added to the grunt
test
task. You can also manually rungrunt eslint:fix
to fix style issues. - Testing is done with Mocha and Karma (all:
grunt karma
, headless:grunt karma:headless
, browsers:grunt karma:browsers
) - Tests can be run in watch mode for TDD workflows with
npm run test-watch
, and support for debugging in VSCode is provided. For instructions see Debugging test watch mode in VSCode below - When making a pull request, please add tests where relevant
Debugging test watch mode in VSCode
Basic usage:
- Go to VSCode's "Run and Debug" panel
- Select "Test (watch + debug)"
- Click the play button
Optionally, you can add a keyboard shortcut to select launch tasks:
- Open the keyboard shortcuts settings (cmd+k cmd+s on Mac, ctrl+k ctrl+s on other OSes)
- Search for
workbench.action.debug.selectandstart
- Click the + button to add your preferred keybinding keybinding
Notes for CSS Developers
The core can be fairly easily extended with alternative themes. See the plain, the grid, and the formhub themes already included in /src/sass. We would be happy to discuss whether your contribution should be a part of the core, the default theme or be turned into a new theme.
For custom themes that go beyond just changing colors and fonts, keep in mind all the different contexts for a theme:
- non-touchscreen vs touchscreen (add ?touch=true during development)
- default one-page-mode and multiple-pages-mode
- right-to-left form language vs left-to-right form language (!) - also the UI-language may have a different directionality
- screen view vs. print view
- questions inside a (nested) repeat group have a different background
- large screen size --> smaller screen size ---> smallest screen size
- question in valid vs. invalid state
Release a new version
Documentation is auto-generated and is re-built for each new release. Do not commit updated documentation in non-release commits. The process to follow for each release that includes various helpful checks is:
- Check Dependabot alerts for vulnerabilities
- Update dependencies:
npm update
. If enketo-transformer is updated, bump the version insrc/js/form.js
npm audit fix
- Make sure tests pass:
npm run test
andnpm run test-browsers
- Beautiful code:
npm run beautify
- Build documentation:
npm run build-docs
- Bump the version tag in
package.json
file (we follow semantic versioning). Bump to major version if downstream has to make changes. - Merge all your changes to
master
(through PR) - Add git tag of new version
- Publish module to NPM:
npm publish