Skip to content

Latest commit

 

History

History
297 lines (204 loc) · 14.2 KB

contributing.md

File metadata and controls

297 lines (204 loc) · 14.2 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 ([email protected]). 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 [email protected]:<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 [email protected]: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...
 */

Documentation

The documentation for the different modules should be clear and consistent. Explanations should be concise, and examples of code should be included where appropriate. In terms of format and style, here are a few suggestions to keep the documentation consistent within a module and across all parts of CanJS:

When referencing another part of CanJS, make sure to link the first reference in a section.

For instance, when documenting can.Component.scope, the first reference to can.Component, can.route, or any other part of CanJS should be enclosed in square brackets, so that links to those docs are generated. Linking each occurrence isn't necessary, but all the other references should at least be surrounded by "grave accents" or tickmarks.

This is an example of linking to [can.Component] from another page. If you reference
`can.Component` later in this section, you don't have to link to it. All subsequent
references to `can.Component` have grave accents or tickmarks surrounding them.

### New Section

Another section referencing [can.Component] starts this trend again...

Note: The one exception to this is on the module page. When documenting can.Component itself, only use the tickmarks, as linking to can.Component would just link to the page you are currently modifying.

Enclose string literals in tickmarks as they should appear in code

If the developer should type "@", use the tickmarks to make this clear. This avoids the ambiguity of whether the apostrophes or quote marks are part of the text that should be typed. This also applies to any references to variable/key names (e.g., scope versus "scope" or scope).

Include a clear description of your example code

For a developer that's new to CanJS, the description of the example is likely more important than the example itself. Make sure there is a clear description of what the code should accomplish. This includes using all the techniques above. A good description should answer the question, "could you explain what this example code is doing?"

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.