Building and Testing

Grunt is used to manage the build and test pipeline.

Testing

Testing is done with Jasmine as the test runner.

Mitm is used to intercept HTTP requests and return recorded responses. Requests are mapped to a JSON file containing the recorded response. Responses are stored in the test/mock directory. The response filename is calculated by the getFilename function in test/unit/helpers.js.

When tests are run, the SDK is attached to the global scope as FamilySearch. An instance of the client is attached to the global scope as FS.

When changes are pushed to GitHub, the test suite is automatically run by Travis-CI.

Code coverage is generated by Istanbul then sent to Coveralls.io for processing.

Building

When all tests pass on the master branch in Travis, the SDK is packaged via Browserify and then minified. Browserify allows us to write the SDK for node (leveraging modules via require) and then package it up into one self-contained JS file for use in the browser.

Documentation

When the master branch is updated and all tests pass in Travis, the docs are built by ngdocs and the gh-pages branch is automatically updated to host the docs. Each minor version of the SDK has its own docs. The minor version should be changed whenever new functionality is added therefore we try to accurately reflect in the docs what functionality each version supports. Patch versions update the appropriate docs because they should only include doc and bug fixes.

The list of available versions in the docs needs to be updated manually. This can be done by editing the index.html in the gh-pages branch. We have yet been unable to find a sane way to update this automatically.

Releases

Steps for cutting a new release (new version):

1. Update the version in package.json then commit and push to GitHub.
2. Wait for the build to finish in Travis so that the gh-pages branch is updated.
3. Tag the updated gh-pages branch with the new version via the Releases tab in GitHub.

The gh-pages branch must be tagged, as opposed to the master branch, so that the CDN jsDelivr can find the packaged version of the SDK for distribution.

We recommend working on a development branch and then only pushing to master when you're ready to cut a release. The reason is that the version in the package.json file determines both which version of the docs get updated as well as if/when anything is published on npm. If you were planning to add multiple features which each new feature in a separate commit to master, you might think you could bump the minor version number so that a new version of the docs is created. However that will publish a new version to npm which won't contain any of the later features you add. To get around this, you commit to a development branch and rev the version number there when you're ready, then merge all the changes into the master branch at once and publish the release.