How to Contribute

  • page
contributing  

Thank you for contributing to CanJS! If you need any help setting up a CanJS development environment and fixing CanJS bugs, please reach out to us on IRC or email (contact@bitovi.com). We will happily walk you throuygh setting up a the environment, creating a test, and submitting a pull request.

Reporting Bugs

To report a bug, please visit GitHub Issues.

When filing a bug, it is helpful to include:

  • Small examples using tools like JSFiddle. You can fork the following CanJS fiddles:
  • Breaking unit tests (optional)
  • Proposed fix solutions (optional)

Search for previous tickets, if there is one add to that one rather than creating another. You can also post on the Forums or talk to us in IRC #canjs channel.

Installing

1.) Fork Canjs on GitHub.

2.) Clone it with:

git clone git@github.com:<your username>/canjs

Developing

After installing CanJS, you’ll find a folder for each feature of CanJS: construct, control, model, etc.

Within each feature folder, for example construct, you’ll find a file for:

  • the implementation of the feature - construct.js
  • a demo of the feature - construct.html
  • an overview documentation page - construct.md
  • the feature’s tests - construct_test.js
  • a page to run those tests - test.html

Any plugins for that feature will be folders within the feature’s folder. Ex: proxy, super.

The can/test folder contains:

  • an index.html page which runs all tests for each library in an iFrame.
  • a test page for each library e.g. jquery.html which loads dependencies using our package manager StealJS
  • a build folder which contains the same set of test files but for testing the build artifacts (like can.jquery.js etc.) you get from the download)
  • an amd folder which runs the same tests for the AMD modules using RequireJS

The can/util folder contains the compatibility layer for each library.

To develop CanJS:

  1. Edit the feature’s file.
  2. Add tests to the feature’s test file.
  3. Open the feature’s test page. Make sure it passes.
  4. Open can/test/index.html in every browser to test everything.
  5. Submit a pull request!

Contributing

When contributing, include tests with new features or bug fixes in a feature branch until you're ready to submit the code for consideration; then push to the fork, and submit a pull request.

Move into the directory of your cloned repository and create a new feature branch.

cd canjs
git checkout -b html5-fix

Once your happy with your changes, push to the feature branch.

git push origin html5-fix

Now you'll need to submit a Pull Request. Navigate to Pull Requests and click the 'New Pull Request' button. Fill in some details about your potential patch including a meaningful title. When finished, press "Send pull request". The core team will be notified about your submission and let you know of any problems or targeted release date.

Documentation

If your pull request affects the public API, make relevant changes to the documentation. Documentation is found either inline or in markdown files in the respective directory. In order to view your changes in documentation you will need to run CanJS.com locally and regenerate the docs. Note that you will need to modify the can folder in the canjs.com clone to point at your local clone of CanJS. This can be accomplished by replacing the can folder in your canjs.com clone with a symlink, ie mv can can.submodule && ln -s <local path to canjs> can.

    git clone git@github.com:bitovi/canjs.com.git
    cd canjs.com
    git checkout gh-pages
    git submodule update --init --recursive
    npm install
    grunt
    ./js scripts/doc.js

Once the documentation is finished rendering, all the HTML files will be located in the docs folder. Open the documentation file you made changes to and make sure everything rendered correctly.

Running Tests Locally

Its important that all tests pass before sending a pull request. TravisCI will determine if your commits pass the tests, but while your developing you can run the QUnit tests locally. To run tests locally you need NodeJS installed and run

npm install

Then open ~/can/test/test.html in a web browser to run all tests for all libraries. Each module has its own tests too, you can run them by opening the test.html in each folder.

CanJS supports the following browsers:

  • Chrome Current-1
  • Safari Current-1
  • Firefox Current-1
  • IE 7+
  • Opera Current-1

Making a build

To make a build (standalone and AMD version) and run tests from the command line you will need NodeJS and Grunt (npm install grunt-cli -g) installed. Then, in the CanJS repository folder run:

npm install

Then you can run:

grunt build

It puts the downloads in can/dist.

You can also run the tests from the command line by executing:

grunt test

Style Guide

Linting

Grunt provides a quality task to verify some basic, practical soundness of the codebase. The options are preset.

Spacing

Indentation with tabs, not spaces.

if/else/for/while/try always have braces, with the first brace on the same line. For example:

if(foo){

}

Spaces after commas. For example:

myfn = function(foo, bar, moo){ ... }

Assignments

Assignments should always have a semicolon after them.

Assignments in a declaration should always be on their own line. Declarations that don't have an assignment should be listed together at the start of the declaration. For example:

// Bad
var foo = true;
var bar = false;
var a;
var b;

// Good
var a, b,
    foo = true,
    bar = false;

Equality

Strict equality checks === should be used in favor of ==. The only exception is when checking for undefined and null by way of null.

// Bad
if(bar == "can"){ ... }

// Good
if(bar === "can"){ ... }

If the statement is a truthey or falsey, use implied operators. Falseys are when variables return false, undefined, null, or 0. Trutheys are when variables return true, 1, or anything defined.

For example:

    // Bad
    if(bar === false){ ... }

    // Good 
    if(bar){ ... }

    // Good
    var foo = [];
    if(!foo.length){ ... }

Quotes

Use double quotes.

var double = "I am wrapped in double quotes";

Strings that require inner quoting must use double outside and single inside.

var html = "<div id='my-id'></div>";

Comments

Single line comments go OVER the line they refer to:

    // We need an explicit "bar", because later in the code foo is checked.
    var foo = "bar";

For long comments, use:

    /* myFn
     * Four score and seven—pause—minutes ago...
     */

List of heroes

The following lists everyone who's contributed something to CanJS. If we've forgotten you, please add yourself.

First, thanks to everyone who's contributed to JavaScriptMVC and jQueryMX, and the people at Bitovi. You deserve heaps of recognition as CanJS is direcly based off JavaScriptMVC. This page is for contributors after CanJS's launch. Thank you

for helping us with new features, bug fixes, and getting this out the door.