can

<!DOCTYPE html>  <html lang="en"> <head> <meta charset="utf-8"> <title>CanJS - Code</title> <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no"> <link rel="stylesheet" type="text/css" href="../../static/bundles/bit-docs-site/static.css"> <link rel="shortcut icon" sizes="16x16 24x24 32x32 48x48 64x64" href="/docs/images/canjs_favicon.ico"> <link rel="apple-touch-icon" sizes="57x57" href="../../../docs/images/canjs_favicon_57x57.png"> <link rel="apple-touch-icon-precomposed" sizes="57x57" href="../../../docs/images/canjs_favicon_57x57.png"> <link rel="apple-touch-icon" sizes="72x72" href="../../../docs/images/canjs_favicon_72x72.png"> <link rel="apple-touch-icon" sizes="114x114" href="../../../docs/images/canjs_favicon_114x114.png"> <link rel="apple-touch-icon" sizes="120x120" href="../../../docs/images/canjs_favicon_128x128.png"> <link rel="apple-touch-icon" sizes="144x144" href="../../../docs/images/canjs_favicon_144x144.png"> <link rel="apple-touch-icon" sizes="152x152" href="../../../docs/images/canjs_favicon_152x152.png"> <meta content="yes" name="apple-mobile-web-app-capable"> <meta name="apple-mobile-web-app-status-bar-style" content="white-translucent"> <script> (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) })(window,document,'script','https://www.google-analytics.com/analytics.js','ga'); ga('create', 'UA-2302003-11', 'auto'); ga('send', 'pageview'); </script> </head> <body> <input type="checkbox" id="nav-trigger" class="nav-trigger"/> <label for="nav-trigger">Menu</label> <div id="everything"> <div id="left" class="column"> <div class="top-left"> <div class="brand"> <div class="logo"> <a href="../../../index.html" alt="CanJS"></a> <div class="dropdown project-dropdown"> <a href="https://donejs.com/">DoneJS</a> <a href="http://stealjs.com/">StealJS</a> <a href="http://jquerypp.com/">jQuery ++</a> <a href="https://funcunit.com/">FuncUnit</a> <a href="http://documentjs.com/">DocumentJS</a> </div> </div> <div class="version"> <div class="version-number"> 3.0.0 </div> <div class="dropdown version-dropdown"> <a href="https://v2.canjs.com">2.3.27</a> </div> </div> </div> <div class="search-bar"> <p>   </p> </div> </div> <div class="bottom-left"> <div class="social-side-container"> <ul class="social-side"> <li> <a class="header-mobile github" href="https://github.com/canjs/canjs" target="_blank"><img class="social-icon-small" src="../../../docs/images/github.png">Github</a> </li> <li> <a class="header-mobile twitter" href="https://twitter.com/canjs" target="_blank"><img class="social-icon-small" src="../../../docs/images/twitter.png">Twitter</a> </li> </ul> <ul class="social-side"> <li> <a class="header-mobile" href="https://gitter.im/canjs/canjs" target="_blank">Chat</a> </li> <li> <a class="header-mobile" href="http://forums.donejs.com/c/canjs" target="_blank">Forum</a> </li> </ul> </div> <ul> <li class=" parent expanded"> <a class="page" href="../../guides.html" title="Welcome to CanJS! These guides are here to help you develop and improve your relationship with CanJS. After all, picking a JavaScript framework is a commitment. We want CanJS to be the framework you marry. This page helps you know how advance through the different stages of this relationship:"> Guides </a> <ul> <li> <span>introduction</span> <ul> <li class=" "> <a class="page" href="../mission.html" title="Learn about CanJS's mission, why it matters, and how we've worked (and will keep working) to accomplish it."> Mission </a> </li> <li class=" "> <a class="page" href="../technical.html" title=""> Technical Highlights </a> </li> <li class=" "> <a class="page" href="../who-uses-canjs.html" title=""> Who uses CanJS? </a> </li> </ul> </li> <li> <span>experiment</span> <ul> <li class=" "> <a class="page" href="../chat.html" title="This guide walks through building real time chat application with CanJS's Core libraries. It takes about 30 minutes to complete."> Chat Guide </a> </li> <li class=" "> <a class="page" href="../todomvc.html" title="This guide walks through building a slightly modified version of TodoMVC with CanJS's Core libraries and can-fixture. It takes about 1 hour to complete."> TodoMVC Guide </a> </li> <li class=" "> <a class="page" href="../atm.html" title="This guide walks through building and testing an ATM application with CanJS's Core libraries. It teaches how to do test driven development (TDD) and manage complex state. It takes about 2 hours to complete."> ATM Guide </a> </li> <li class=" "> <a class="page" href="../setup.html" title="CanJS is packaged in multiple ways so that it can fit into any development workflow. Learn how to setup CanJS in different environments."> Setting up CanJS </a> </li> </ul> </li> <li> <span>commitment</span> <ul> <li class=" "> <a class="page" href="../api.html" title="This page walks through how to use and understand CanJS's API documentation."> API Guide </a> </li> <li class=" "> <a class="page" href="../examples.html" title=""> Examples </a> </li> <li class=" "> <a class="page" href="../../roadmap.html" title="Learn about CanJS's future plans and how we make them, and how you can influence them."> Roadmap </a> </li> <li class=" "> <a class="page" href="../../migrate-3.html" title=""> Migrating to 3.0 </a> </li> </ul> </li> <li> <span>contribute</span> <ul> <li class=" "> <a class="page" href="bug-report.html" title="Learn how to submit a bug report."> Bug Report </a> </li> <li class="current parent expanded"> <a class="page" href="code.html" title="Learn how contribute a code change to CanJS."> Code </a> </li> <li class=" "> <a class="page" href="documentation.html" title="Learn how to improve CanJS's site and documentation."> Documentation </a> </li> <li class=" "> <a class="page" href="evangelism.html" title="Learn about resources that can help you spread the word about CanJS."> Evangelism </a> </li> <li class=" "> <a class="page" href="feature-suggestion.html" title="Learn how to suggest a feature."> Feature Suggestion </a> </li> <li class=" "> <a class="page" href="releases.html" title="Release and hosting information for CanJS maintainers."> Releases </a> </li> </ul> </li> </ul> </li> <li class=" "> <a class="page" href="../../can-core.html" title="The best, most hardened and generally useful libraries in CanJS."> Core </a> </li> <li class=" "> <a class="page" href="../../can-ecosystem.html" title="Useful libraries that extend or add important features to the core collection."> Ecosystem </a> </li> <li class=" "> <a class="page" href="../../can-infrastructure.html" title="Utility libraries that power the core and ecosystem collection."> Infrastructure </a> </li> <li class=" "> <a class="page" href="../../can-legacy.html" title="Former libraries that we still accept patches for, but are not under active development."> Legacy </a> </li> </ul> </div> </div> <div id="right" class="column"> <div class="top-right"> <div class="top-right-top"> <ul class="top-right-bitovi"> <li class="dropdown"> <a href="http://bitovi.com" class="bitovi icon-bits">Bitovi</a> <ul class="dropdown-menu"> <li><a href="http://bitovi.com">Bitovi.com</a></li> <li><a href="http://bitovi.com/blog/">Blog</a></li> <li><a href="http://bitovi.com/consulting/">Consulting</a></li> <li><a href="http://bitovi.com/training/">Training</a></li> <li><a href="http://bitovi.com/open-source/">Open Source</a></li> </ul> </li> </ul> <div class="brand"> <div class="logo"> <a href="../../../index.html" alt="CanJS"></a> </div> </div> <ul class="top-right-links"> <li> <a href="https://gitter.im/canjs/canjs">Chat</a> </li> <li> <a href="http://forums.donejs.com/c/canjs">Forum</a> </li> <li> <a class="github-button nav-social" href="https://github.com/canjs/canjs" data-count-href="/canjs/canjs/stargazers" data-count-api="/repos/canjs/canjs#stargazers_count">Star</a> </li> <li> <a href="https://twitter.com/canjs" class="twitter-follow-button nav-social" data-show-count="true" data-show-screen-name="false">Follow @canjs</a><script async src="//platform.twitter.com/widgets.js" charset="utf-8"></script> </li> </ul> </div> <div class="breadcrumb"> <li><a href="../../../index.html">CanJS</a></li> / <li><a href="../../guides.html">Guides</a></li> / <li><a href="code.html">Code</a></li> <li class="breadcrumb-dropdown">/ <a> On this page</a> <ul class="on-this-page"></ul> </li> <div class="nav-toggle" title="Back to top"></div> </div> </div> <div class="bottom-right"> <article> <section class="title"> <div class="page-type"> <h1>Code</h1> <div>page</div> </div> <section class="description"> <p>Learn how contribute a code change to CanJS.</p> </section> </section> <section class="on-this-page-table"> </section> <section class="title-footer"> <ul class="title-links">  <li><a href="//github.com/canjs/canjs/tree/v3.0.0/docs/can-guides/contribute/code.md">source</a></li>   </ul> </section> <section class="body"> <h2>Overview</h2> <p>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 setup a pairing session to show you how to fix a bug or write a feature.</p> <p>If you have any questions, you can always reach us on <a href="https://gitter.im/canjs/canjs">Gitter chat</a>.</p> <p>The first thing to know about <code>CanJS</code> is that its code is split across about 40 different repositories. All but one of these repositories are <strong>library</strong> repositories like <a href="https://github.com/canjs/can-event">canjs/can-event</a> and <a href="https://github.com/canjs/can-define">canjs/can-define</a>. These all work the same way. The <a href="https://github.com/canjs/canjs">canjs/canjs</a> <strong>framework</strong> repository works slightly differently. The vast majority of code changes happen in one of the <strong>library</strong> repositories.</p> <p>If you don't know which repository you need to work on, ask us in <a href="https://gitter.im/canjs/canjs">Gitter chat</a>.</p> <p>Once you know your repository, the following details:</p> <ul> <li>Setting up your development environment.</li> <li>Getting the repository's code and verify it's working.</li> <li>The file organization and responsibilities.</li> <li>Making changes and submitting a pull request.</li> </ul> <p>The following video walks through most of the following steps:</p> <iframe width="560" height="315" src="https://www.youtube.com/embed/PRuueWqnpIw" frameborder="0" allowfullscreen></iframe> <h2>Setting up your development environment.</h2> <p>Developing CanJS requires:</p> <ul> <li>A <a href="github.com">https://github.com/</a> account and git client.</li> <li>Node version 5 or later.</li> <li>Firefox for running automated tests.</li> </ul> <h3>Getting github account and client</h3> <p>Signup for a <a href="GitHub">https://github.com/</a> account.</p> <p>There are a variety of ways to get a git command line client connected to your GitHub account. Fortunately, GitHub has great documentation on how to <a href="https://help.github.com/articles/set-up-git/">Setup Git</a>.</p> <p>If you already have <code>git</code> installed, make sure you've <a href="https://help.github.com/articles/adding-a-new-ssh-key-to-your-github-account/">setup your ssh keys</a>.</p> <h3>Get NodeJS</h3> <p>Download Node.js version 5 or later at <a href="https://nodejs.org">https://nodejs.org</a>. You can verify node is working at its version with:</p> <pre><code>> node -v </code></pre> <h3>Get Firefox</h3> <p>Download the Firefox browser <a href="https://www.mozilla.org/en-US/firefox/new/">here</a>. Make sure it gets installed into the default location for your operating system.</p> <p>Firefox is used to run each repository's tests.</p> <h2>Getting the code and verify it is working</h2> <p>Once your environment is setup, you should be able to clone the repository you want to change, install its dependencies, and verify you've setup your development environment correctly.</p> <p><strong>1.</strong> Fork the repository you are working from by clicking the <code>fork</code> button. For example, you can fork <code>can-compute</code> by pressing its <strong>fork</strong> button on GitHub:</p> <p><img src="../../../docs/can-guides/contribute/fork.png" width="600px"/></p> <p><strong>2.</strong> Clone the your forked version of the repository.</p> <pre><code>> git clone git@github.com:<your username>/<repository-name>.git </code></pre> <p>For example, if your username is <code>justinbmeyer</code>, and you forked <code>can-compute</code>:</p> <pre><code>> git clone git@github.com:justinbmeyer/can-compute.git </code></pre> <p>Before the next step, make sure you move into your project's directory. For example:</p> <pre><code>> cd can-compute </code></pre> <p><strong>3.</strong> Install npm dependencies with:</p> <pre><code>> npm install </code></pre> <p><strong>4.</strong> Make sure Firefox is closed and run the test suite with:</p> <pre><code>> npm test </code></pre> <p>If every test passed, <strong>congrats</strong>! You've got everything you need to change code and send it back to us.</p> <h2>File organization and responsibilities</h2> <p>Most <strong>library</strong> repositories share a similar structure. Understanding it can help you figure out what code needs to be changed. The following details the directory structure of a nonexistent <code>can-example</code> repository:</p> <pre><code>├── package.json - Configuration of package and dev scripts ├── can-example.js - Main module code ├── build.js - Build script to export code in other formats ├── .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 ├── readme.md - Automatically generated readme ├── test/ - Test files | ├── can-example-test.js - Main test file | ├── test.html - Main test page ├── docs/ - Documentation source | ├── can-example.md - Package or module documentation ├── node_modules/ - Node dependency installation folder </code></pre> <p>Generally, speaking, the most important files are:</p> <ul> <li>the main module - <code>can-example.js</code></li> <li>the main test module - <code>test/can-example-test.js</code></li> <li>the test page - <code>test/test.html</code></li> </ul> <p>When fixing a bug or making a feature, we'll add a test in the main test module and update code in the main module and verify the tests are passing by running the test page.</p> <p>Some modules have multiple modules, test modules, and test pages. These modules are commonly organized as <strong>modlets</strong> where each folder will have its own main module, test module and test page:</p> <pre><code>├── 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 </code></pre> <p>Where possible, CanJS code is:</p> <ul> <li>Tabs not spaces</li> <li>JSHinted</li> <li>CommonJS not ES6</li> <li>Follows jQuery <a href="https://contribute.jquery.org/style-guide/js/">coding conventions</a></li> </ul> <h2>Make your changes</h2> <p>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:</p> <ol> <li>Create a new feature branch. For example, <code>git checkout -b html5-fix</code>.</li> <li>Make some changes to the code and tests.</li> <li>Run tests <code>npm test</code> and make sure they pass in all browsers.</li> <li>Update documentation if necessary.</li> <li>Push your changes to your remote branch. For example, <code>git push origin html5-fix</code>.</li> <li>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.</li> </ol> <p>If you enjoy making these kinds of fixes, and want to directly influence CanJS's direction, consider joining our <a href="https://donejs.com/About.html#section=section_Coreteam">Core team</a>.</p> <h2>Making a plugin</h2> <p>Making an official or un-offical CanJS plugin is easy.</p> <p>An <strong>offical</strong> plugin is:</p> <ul> <li>In a repository under the <a href="https://github.com/canjs" title="CanJS organization">CanJS organization</a>.</li> <li>Listed and documented under the <a href="../../can-ecosystem.html" title="Useful libraries that extend or add important features to the core collection.">Ecosystem Collection</a>.</li> <li>Tested in the <code>canjs/canjs</code> integration suite.</li> <li>With few exceptions, published as <code>can-<name></code> .</li> </ul> <p><strong>Unofficial</strong> plugins can be maintained however you choose, but to maximize your project's:</p> <ul> <li>Compatibility - useful in as many development environments as possible (RequireJS, Browserify, Webpack, etc)</li> <li>Discoverability - other developers can find it</li> <li>Contribute-ability - other developers can contribute to it</li> </ul> <p>... we suggest following the <a href="https://donejs.com/plugin.html">DoneJS plugin</a> with the following changes:</p> <p><strong>1.</strong> Pick a plugin name that has <code>can</code> in the name.</p> <p><strong>2.</strong> When the <code>donejs add plugin</code> generator asks for "Project main folder", use <code>.</code></p> <p><strong>3.</strong> List <code>canjs</code> in your <code>package.json</code>'s <code>keywords</code>.</p> <p><strong>4.</strong> Update the code to match the <a href="#Fileorganizationandresponsibilities">File organization and responsibilities</a> section. There are a few changes to make:</p> <ul> <li>Change everything to CommonJS. Use <code>require('module-name')</code> instead of <code>import 'module-name'</code>.</li> <li>Use <em>tabs</em> instead of <em>spaces</em>.</li> <li>Use dashes instead of underscores in generated filenames.</li> </ul> </section> <script type="text/javascript"> var docObject = {"src":{"path":"docs/can-guides/contribute/code.md"},"description":"Learn how contribute a code change to CanJS. \n","name":"guides/contributing/code","title":"Code","type":"page","parent":"guides/contribute","comment":" ","pathToRoot":"../../.."}; </script> </article> <footer><p>CanJS is part of <a href="http://donejs.com" target="_blank">DoneJS</a>. Created and maintained by the core <a href="https://donejs.com/About.html#section=section_Team" target="_blank">DoneJS team</a> and <a href="http://bitovi.com" target="_blank">Bitovi</a>. <strong>Currently 3.0.0.</strong></p></footer> </div> </div> </div> <script> steal = { instantiated: { "bundles/bit-docs-site/static.css!$css" : null } }; </script> <script type='text/javascript' data-main="bit-docs-site/static" src="../../static/node_modules/steal/steal.production.js"></script> <script async defer src="https://buttons.github.io/buttons.js"></script> </body> </html>