Skip to content

Latest commit

 

History

History
271 lines (190 loc) · 12.1 KB

contributing.md

File metadata and controls

271 lines (190 loc) · 12.1 KB
Raw

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 the #canjs IRC channel or email (contact@bitovi.com). We will happily walk you through 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 #canjs IRC channel.

Installing

  1. Fork Canjs on GitHub.
  2. Clone it with: git clone git@github.com:<your username>/canjs

Structure

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.

Contributing

When contributing, please 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. More detailed steps are as follows:

  1. Navigate to your clone of the CanJS repository - cd /path/to/canjs
  2. Create a new feature branch - git checkout -b html5-fix
  3. Make some changes
  4. Update tests to accomodate your changes
  5. Run tests and make sure they pass in all browsers
  6. Update documentation if necessary
  7. Push your changes to your remote branch - git push origin html5-fix
  8. 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.

Testing

CanJS has a pretty comprehensive test suite that is constantly being added to. Each module has its own tests, that can be run by opening the test.html in each folder. It's important that all tests pass before sending a pull request. TravisCI will determine if your commits pass the tests, but while you're developing you can run the QUnit tests locally.

There are 3 ways of running your tests locally, all of which will require you to have NodeJS, npm, Grunt and all of the CanJS dev dependencies installed.

Getting Set Up

  1. Install NodeJS & npm - NodeJS or use brew install nodejs
  2. Install Grunt - npm install grunt-cli -g
  3. Navigate to your local clone of CanJS - cd /path/to/canjs
  4. Install dependencies - npm install

Running All Tests From CLI

  1. Once you completed the steps above simply run grunt test.

Running All Tests In Browser

  1. grunt connect:server:keepalive
  2. Open http://localhost:8000/test/ in your browser.

Running Individual Test Files

  1. grunt connect:server:keepalive
  2. Open http://localhost:8000/ in your browser and then navigate to your intended file.

CanJS supports the following browsers:

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

Documentation

If your changes affect the public API, please 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 the CanJS.com site locally and regenerate the docs.

Note:

You will need to make sure that the can folder in your clone of canjs.com points to your local copy of CanJS where you made the documentation changes. This can be accomplished by replacing the can folder in your canjs.com clone with a symlink, using: 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.

Making a build

To make a build (standalone and AMD version) you will also need to have [NodeJS, npm, Grunt and all of the CanJS dev dependencies installed.

Getting Set Up

  1. Install NodeJS & npm - NodeJS or use brew install nodejs
  2. Install Grunt - npm install grunt-cli -g
  3. Navigate to your local clone of CanJS - cd /path/to/canjs
  4. Install dependencies - npm install

After you have completed those steps simply run grunt build and it will put the built files in the can/dist directory, making them ready for download.

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.