Learn how contribute a code change to CanJS.
Contributing to any Open Source project can be intimidating. All contributions from all types of contributors are welcome. We’re committed to making the experience as pleasant and rewarding as possible. We’re happy to set up a pairing session to show you how to fix a bug or write a feature.
If you have any questions, you can always reach us on Gitter chat.
The first thing to know about
CanJS is that its code is split across about 40 different
repositories. All but one of these are library repositories like
canjs/can-event and canjs/can-define. These all work the same way.
The canjs/canjs framework repository works slightly
differently. The vast majority of code changes happen in one of the library
If you don’t know which repository you need to work on, ask us in Gitter chat.
We’ll cover the following details in this guide:
- Setting up your development environment.
- Getting the repository’s code and verify it’s working.
- The file organization and responsibilities.
- Making changes and submitting a pull request.
The following video walks through most of the following steps:
Setting up your development environment
Developing CanJS requires:
- A GitHub account and git client.
- Node.js version 5 or later.
- Firefox for running automated tests.
Getting GitHub account and client
Sign up for a GitHub account.
There are a variety of ways to get a git command line client connected to your GitHub account. GitHub has great documentation on how to set up Git.
If you already have
git installed, make sure you’ve
set up your ssh keys.
Download Node.js version 5 or later at NodeJS.org. You can verify Node’s version with:
Download the Firefox browser here. Make sure it gets installed into the default location for your operating system.
Firefox is used to run each repository’s tests.
Getting the code and verifying that it’s working
Once your environment is set up, you should be able to clone the repository you want to change, install its dependencies, and verify you’ve set up your development environment correctly.
1. Click the Fork button to fork the repository from which you will be working.
For example, you can fork
can-compute by pressing its Fork button on GitHub:
2. Clone your forked version of the repository:
git clone [email protected]:<your username>/<repository-name>.git
For example, if your username is
justinbmeyer and you forked
git clone [email protected]:justinbmeyer/can-compute.git
3. Move into your project’s directory. For example
4. Install npm dependencies with:
5. Make sure Firefox is closed and run the test suite with:
If every test passed, congrats! You have everything you need to change code and have the core team review it.
File organization and responsibilities
Most library repositories share a similar structure. Understanding it can help
you figure out what code needs to be changed. The following outline shows the
directory structure of a nonexistent
├── .editorconfig — Configures editors for this project ├── .gitignore — Tells git to ignore certain files ├── .jshintrc — Configures JSHint ├── .npmignore — Tells npm publish to ignore certain files ├── .travis.yml — Travis CI configuration ├── build.js — Build script to export code in other formats ├── can-example.js — Main module code ├── package.json — Configuration of package and dev scripts ├── readme.md — Automatically generated readme ├── docs/ — Documentation source | ├── can-example.md — Package or module documentation ├── node_modules/ — Node dependency installation folder ├── test/ — Test files | ├── can-example-test.js — Main test file | ├── test.html — Main test page
Generally speaking, the most important files are:
- the main module —
- the main test module —
- the test page —
To fix a bug or making a feature, add a test in the main test module, update code in the main module, and then verify the tests are passing by running the test page.
Some modules have multiple modules, test modules, and test pages. These modules are commonly organized as modlets where each folder will have its own main module, test module, and test page:
├── a-module/ — Module’s modlet folder | ├── a-module.js — The module | ├── a-module-test.js — The module’s tests | ├── test.html — A test page that runs just the module’s tests
Where possible, CanJS code uses:
- Tabs not spaces
- CommonJS not ES6
- jQuery’s coding conventions
Make your changes
Once you’ve figured out where you need to make changes, you’ll want to complete the following steps to make those changes and create a pull request so we can include your code in future releases:
- Create a new feature branch. For example,
git checkout -b html5-fix.
- Make some changes to the code and tests.
npm testto make sure the tests pass in all browsers.
- Update the documentation if necessary.
- Push your changes to your remote branch. For example,
git push origin html5-fix.
- Submit a pull request! On GitHub, 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 of your submission and will let you know of any problems or a targeted release date.
If you enjoy making these kinds of fixes and want to directly influence CanJS’s direction, consider joining our Core team.
Making a plugin
Making an official or unofficial CanJS plugin is easy.
An official plugin is:
- In a repository under the CanJS organization.
- Listed and documented under the Ecosystem Collection.
- Tested in the
- Published as
can-<name>(with a few exceptions).
Unofficial plugins can be maintained however you choose, but to maximize your project’s:
- Compatibility — useful in as many development environments as possible (Browserify, StealJS, Webpack, etc.)
- Discoverability — other developers can find it
- Contribute-ability — other developers can contribute to it
…we suggest following the DoneJS plugin guide with the following changes:
1. Pick a plugin name that has
can in the name.
2. When the
donejs add plugin generator asks for “Project main folder”, use
canjs in your
4. Update the code to match the File organization and responsibilities section. There are a few changes to make:
- Change everything to CommonJS. Use
- Use tabs instead of spaces.
- Use dashes instead of underscores in generated filenames.