Compute.io

A contributing guide.

Table of Contents

1. Overview
2. Joining
3. Style Guide
   • Type Checking
4. Getting Started
5. Tests
6. Workflow
7. Versioning
8. Licensing

Overview

Compute.io is a JavaScript computation library. Each library function is written as a standalone module which can be independently imported into any application or project.

Monolithic libraries can be beneficial in the sense that these libraries centralize a codebase. Rarely, however, does one require all library functionality. All too often an application requires only one library function; in which case, the rest of the library is unnecessary and leads to code bloat.

Compute.io is guided by three design principles: composition, consistency, and rigor.

• Composition: standalone modules encourage flexible composition (build your own compute), constrained design (do one thing; do one thing well), and restraint (only use what you need).

• Consistency: all modules should look and feel as if written by a single author. A user should be free to focus on understanding algorithms without the distraction of arbitrary changes in style.

• Rigor: testing and benchmarking should be priorities, not afterthoughts, and algorithms should be robust. Too many "numerical" libraries written in JavaScript implement poor algorithms, lack precision, and disregard performance.

What follows is a guide to contributing to Compute.io.

Joining

Have a great idea for a compute module or want to become more involved? Awesome. :)

You have a couple of options...

1. Create a module linked to your personal Github account and submit a pull request for inclusion in the main compute.io library.
2. (preferred option) Ask an owner to become a compute-io member.

If you opt for option #1, note that all compute modules are expected to follow the same style guide described below.

Style Guide

All compute modules should follow the same JavaScript style guide. Users should not have to decode styles to read and understand what matters: algorithms.

Each module repository should include the following files which enforce style consistency:

• .editorconfig: defines editor settings for compatible editors, such as Sublime Text and Atom.
• .jshintrc: defines JSHint behavior.

Any tasks, such as tests, examples, documentation generation, benchmarking, etc, should be invoked via a Makefile target.

Type Checking

You are strongly encouraged to type check input arguments. While including checks leads to longer modules and more required tests, doing so helps define user expectations and allows users to more easily debug their code.

// Do:
function mmean( win ) {
	if ( typeof win !== 'number' || win !== win || win < 1 ) {
		throw new TypeError( 'win()::invalid input argument. Window size must be a positive integer.')
	}
	// Do something...
}

// Don't:
function mmean( win ) {
	// Do something...
}

Getting Started

Contributors are encouraged to use the Yeoman module generator. The generator automates many aspects of module generation by creating a base scaffold from which to build a compute module.

A couple of notes...

1. Before using the generator, be sure to create a remote repository on Github. The generator will use the repository name to generate the remote URLs included in the package.json and README.md. Additionally, the generator takes care of setting the remote origin for the local Git repository, so you can begin pushing code to the compute-io organization immediately after generation.
2. Before pushing code to Github, be sure to turn on continuous integration using travis-ci, and be sure to turn on code coverage using coveralls. For the savvy, travis-ci can be enabled from the command-line; just ensure that you sync first.

Workflow

The following is a typical workflow when creating compute modules...

1. Create a repository within the Github organization.

2. Enable travis-ci and coveralls.

3. Create a new local directory.

   $ mkdir <repo_name>
   $ cd <repo_name>

4. Run the generator and follow the prompts.

   $ yo compute-io

   Note that the module name should follow the convention of the repository name being prefixed with compute-; .e.g., compute-mean, where mean is the repository name.

5. Open the project in your favorite text editor; e.g.,

   $ subl .

6. Edit the README.md. Define the module's behavior, including example code. Consider this writing a module specification.

7. Copy the example from the README.md to the examples file ./examples/index.js. The executable example code may be modified for clarity and include additional cases, but should at least resemble the example provided in the README.md.

8. Update the package.json keywords. Consider this search engine optimization.

   • If I were searching for this module, what search terms might I use?

9. Write tests against the README.md in ./test/test.js.

   • What are the expected input arguments?
   • What is the output type?
   • What is the expected behavior?

10. Implement the module in ./lib/index.js.

11. Run the tests against the module.

    $ make test-cov

12. Fix broken tests and achieve 100% code coverage.

13. Run the example code and confirm expected output.

    $ node ./examples/index.js

14. Read through the module to ensure everything is correct (e.g., descriptions, code documentation, spelling, edge cases, etc).

15. Commit and push the code to the remote repository.

    $ git add -A
    $ git commit -a
    $ git commit
    $ git push origin master

16. Visit the Github repository. Read the README.md and ensure that everything is correct.

17. After waiting for 1-2 minutes, travis-ci should have attempted to build the module. Confirm that the build succeeded (the README.md badge should transition from pending to passing), and confirm that coveralls received a code coverage report (the README.md badge should show the percent code coverage).

18. Inform an organization owner that the module is ready and a candidate for publishing. An owner will subsequently review the module and suggest any changes which need to be made before publishing and inclusion in the main library.

19. Once the module has been green-lighted, publish the module to NPM.

    $ npm publish

20. Create a new release by creating a new Git tag.

    $ git tag -a v<major.minor.patch> -m "Initial release."
    $ git push origin v<major.minor.patch>

    where the <major.minor.patch> version should be the same version published to NPM.

21. If the module is stable (an owner will confirm this during the module review), bump the version to a stable status (e.g., >=1.0.0).

    $ npm version major -m "[UPDATE] bump version."
    $ git push origin master

22. Publish the updated module to NPM.

    $ npm publish

23. By default, npm version creates a new git tag when run on a git repository. To push the new tag to Github

    $ git push origin --tags

Versioning

Once published, the module should be versioned using semantic versioning.

• Any bug fixes should be patches.
• Any new functionality which is not API breaking should be communicated as a minor update; e.g., additional configuration options, etc.
• Any modified or new functionality which is API breaking should be communicated as a major update.

Once a module is updated and its associated tests are passing, bump the version, push to the remote repository, and publish.

$ npm version <major|minor|patch> -m "<message>"
# => returns the new semver version <major.minor.patch>
$ git push origin master
$ npm publish
$ git push origin --tags

Tests

All modules must instrument testing. Currently, Mocha is the preferred test framework with Chai assertions. For code coverage, you are encouraged to use Istanbul.

If you use the Compute.io generator, the above test modules are included along with stubbed test code. All modules should have 100% code coverage.

Licensing

All modules should be licensed under an MIT license.