Contributing

We love contributions. Yes indeed, we used the word LOVE! But please make sure you follow the same coding style. Here are some guidelines.

Building

After contributing you probably want to build the library to run some specs. Make sure you have Node.js installed on your system, cd to the svg.js directory and run:

$ npm install

Build SVG.js by running gulp:

$ npm run build

The resulting files are:

dist/svg.js
dist/svg.min.js

Testing

There is two ways to run the test suite. One is from the command line and the other is in your browser.
To run the test suite at the command line, you need to have Firefox installed.

$ npm test

To run the test suite in your default browser, simply open /spec/SpecRunner.html. Usually by double click.

If you are the cautious type, you might want to read, before you push, on how to prevent pushing failing commits.

Before you push

Imagine that you're tweaking some part of svg.js and as the responsible person you are, you made sure to run npm test before pushing. Unfortunately npm test tests the current dist/svg.js which only has your edits if you first did npm run build.

This has happened to me a couple of times and as a svg.js contributor, it's embarrassing.

Fortunately git has a pre-push hook which can save yourself from the embarrassment.

I have created a pre-push hook that will build a new dist/svg.js and run the tests. It's developed on Ubuntu 16.04 but should work on all *nix platforms. You can disable this check with:

git push --no-verify

pre-push

#!/bin/sh

npm run build:test && npm run test:quick

# check how the test went
testCode=$?
[ "$testCode" = 0 ] || echo "Your current build does not pass our unit tests - please make them pass before you push"
# revert artifacts created during build
git reset --hard $(git log -1 --pretty=%H)
# exit with the test exit code
exit $testCode

A failed push looks something like this:

git push

> svg.js@2.3.6 build:test /home/dotnet/projects/opensource/svg.js
> gulp unify

[14:20:12] Using gulpfile ~/projects/opensource/svg.js/gulpfile.js
[14:20:12] Starting 'clean'...
[14:20:12] Finished 'clean' after 34 ms
[14:20:12] Starting 'unify'...
[14:20:13] Full svg.js 137.14 kB
[14:20:13] Finished 'unify' after 318 ms

> svg.js@2.3.6 test:quick /home/dotnet/projects/opensource/svg.js
> karma start .config/karma.quick.js

PhantomJS 2.1.1 (Linux 0.0.0) ERROR
  TypeError: undefined is not a function (evaluating 'root.callFailingFooBar()')
  at dist/svg.js:21

npm ERR! Linux 4.4.0-45-generic
npm ERR! argv "/home/dotnet/.nvm/versions/node/v7.0.0/bin/node" "/home/dotnet/.nvm/versions/node/v7.0.0/bin/npm" "run" "test:quick"
npm ERR! node v7.0.0
npm ERR! npm  v3.10.8
npm ERR! code ELIFECYCLE
npm ERR! svg.js@2.3.6 test:quick: `karma start .config/karma.quick.js`
npm ERR! Exit status 1
npm ERR! 
npm ERR! Failed at the svg.js@2.3.6 test:quick script 'karma start .config/karma.quick.js'.
npm ERR! Make sure you have the latest version of node.js and npm installed.
npm ERR! If you do, this is most likely a problem with the svg.js package,
npm ERR! not with npm itself.
npm ERR! Tell the author that this fails on your system:
npm ERR!     karma start .config/karma.quick.js
npm ERR! You can get information on how to open an issue for this project with:
npm ERR!     npm bugs svg.js
npm ERR! Or if that isn't available, you can get their info via:
npm ERR!     npm owner ls svg.js
npm ERR! There is likely additional logging output above.

npm ERR! Please include the following file with any support request:
npm ERR!     /home/dotnet/projects/opensource/svg.js/npm-debug.log
Your current build does not pass our unit tests - please make them pass before you push
HEAD is now at b66f005 Calling new awesome method
error: failed to push some refs to 'https://github.com/dotnetCarpenter/svg.js.git'

Install

Put pre-push in your local SVG.js repository, in the .git/hooks folder and make it executable:

sudo chmod +x .git/hooks/pre-push

To disable the check when you push, write:

git push --no-verify