mermaid

<!DOCTYPE html> <html> <head> <title>CONTRIBUTING.md</title> <meta http-equiv="content-type" content="text/html; charset=UTF-8"> <link rel="stylesheet" media="all" href="../../doc-style.css" /> <script src="../../doc-filelist.js"></script> <script> var relativeDir = "../../", thisFile = "Users/knut/Documents/source/mermaid/bower_components/jasmine/CONTRIBUTING.md", defaultSidebar = true; </script> <script src="../../doc-script.js"></script> <script src="../../mermaid.js"></script> <link rel="stylesheet" href="../../mermaid.css" /> </head> <body> <div id="sidebar_wrapper"> <div id="sidebar_switch"> <span class="tree">Files</span> <span class="headings">Headings</span> </div> <div id="tree"></div> <div id="headings"> <div class="heading h1"> <a href="#Developing for Jasmine Core">Developing for Jasmine Core</a> </div> <div class="heading h2"> <a href="#General Workflow">General Workflow</a> </div> <div class="heading h2"> <a href="#Background">Background</a> </div> <div class="heading h3"> <a href="#Directory Structure">Directory Structure</a> </div> <div class="heading h3"> <a href="#Self-testing">Self-testing</a> </div> <div class="heading h3"> <a href="#`boot.js`"><code>boot.js</code></a> </div> <div class="heading h3"> <a href="#Compatibility">Compatibility</a> </div> <div class="heading h2"> <a href="#Development">Development</a> </div> <div class="heading h3"> <a href="#Install Dependencies">Install Dependencies</a> </div> <div class="heading h3"> <a href="#How to write new Jasmine code">How to write new Jasmine code</a> </div> <div class="heading h3"> <a href="#Running Specs">Running Specs</a> </div> <div class="heading h2"> <a href="#Before Committing or Submitting a Pull Request">Before Committing or Submitting a Pull Request</a> </div> <div class="heading h2"> <a href="#Submitting a Pull Request">Submitting a Pull Request</a> </div> </div> </div> <div id="sidebar-toggle"></div> <div id="container"><div class="docs markdown"><div class="pilwrap" id="Developing for Jasmine Core"> <h1> <a href="#Developing for Jasmine Core" name="Developing for Jasmine Core" class="pilcrow">¶</a> Developing for Jasmine Core</h1> </div> <p>We welcome your contributions - Thanks for helping make Jasmine a better project for everyone. Please review the backlog and discussion lists (the main group - <a href="http://groups.google.com/group/jasmine-js">http://groups.google.com/group/jasmine-js</a> and the developer's list - <a href="http://groups.google.com/group/jasmine-js-dev">http://groups.google.com/group/jasmine-js-dev</a>) before starting work - what you're looking for may already have been done. If it hasn't, the community can help make your contribution better.</p> <div class="pilwrap" id="General Workflow"> <h2> <a href="#General Workflow" name="General Workflow" class="pilcrow">¶</a> General Workflow</h2> </div> <p>Please submit pull requests via feature branches using the semi-standard workflow of:</p> <ol> <li>Fork it</li> <li>Clone your fork: (<code>git clone git@github.com:yourUserName/jasmine.git</code>) </li> <li>Change directory: (<code>cd jasmine</code>) </li> <li>Asign original repository to a remote named 'upstream': (<code>git remote add upstream https://github.com/pivotal/jasmine.git</code>) </li> <li>Pull in changes not present in your local repository: (<code>git fetch upstream</code>)</li> <li>Create your feature branch (<code>git checkout -b my-new-feature</code>)</li> <li>Commit your changes (<code>git commit -am 'Add some feature'</code>)</li> <li>Push to the branch (<code>git push origin my-new-feature</code>)</li> <li>Create new Pull Request</li> </ol> <p>We favor pull requests with very small, single commits with a single purpose.</p> <div class="pilwrap" id="Background"> <h2> <a href="#Background" name="Background" class="pilcrow">¶</a> Background</h2> </div> <div class="pilwrap" id="Directory Structure"> <h3> <a href="#Directory Structure" name="Directory Structure" class="pilcrow">¶</a> Directory Structure</h3> </div> <ul> <li><code>/src</code> contains all of the source files<ul> <li><code>/src/console</code> - Node.js-specific files</li> <li><code>/src/core</code> - generic source files</li> <li><code>/src/html</code> - browser-specific files</li> </ul> </li> <li><code>/spec</code> contains all of the tests<ul> <li>mirrors the source directory</li> <li>there are some additional files</li> </ul> </li> <li><code>/dist</code> contains the standalone distributions as zip files</li> <li><code>/lib</code> contains the generated files for distribution as the Jasmine Rubygem and the Python package</li> </ul> <div class="pilwrap" id="Self-testing"> <h3> <a href="#Self-testing" name="Self-testing" class="pilcrow">¶</a> Self-testing</h3> </div> <p>Note that Jasmine tests itself. The files in <code>lib</code> are loaded first, defining the reference <code>jasmine</code>. Then the files in <code>src</code> are loaded, defining the reference <code>j$</code>. So there are two copies of the code loaded under test.</p> <p>The tests should always use <code>j$</code> to refer to the objects and functions that are being tested. But the tests can use functions on <code>jasmine</code> as needed. <em>Be careful how you structure any new test code</em>. Copy the patterns you see in the existing code - this ensures that the code you're testing is not leaking into the <code>jasmine</code> reference and vice-versa.</p> <div class="pilwrap" id="`boot.js`"> <h3> <a href="#`boot.js`" name="`boot.js`" class="pilcrow">¶</a> <code>boot.js</code></h3> </div> <p><strong>This is new for Jasmine 2.0.</strong></p> <p>This file does all of the setup necessary for Jasmine to work. It loads all of the code, creates an <code>Env</code>, attaches the global functions, and builds the reporter. It also sets up the execution of the <code>Env</code> - for browsers this is in <code>window.onload</code>. While the default in <code>lib</code> is appropriate for browsers, projects may wish to customize this file.</p> <p>For example, for Jasmine development there is a different <code>dev_boot.js</code> for Jasmine development that does more work.</p> <div class="pilwrap" id="Compatibility"> <h3> <a href="#Compatibility" name="Compatibility" class="pilcrow">¶</a> Compatibility</h3> </div> <ul> <li>Browser Minimum<ul> <li>IE8</li> <li>Firefox 3.x</li> <li>Chrome ??</li> <li>Safari 5</li> </ul> </li> </ul> <div class="pilwrap" id="Development"> <h2> <a href="#Development" name="Development" class="pilcrow">¶</a> Development</h2> </div> <p>All source code belongs in <code>src/</code>. The <code>core/</code> directory contains the bulk of Jasmine's functionality. This code should remain browser- and environment-agnostic. If your feature or fix cannot be, as mentioned above, please degrade gracefully. Any code that should only be in a non-browser environment should live in <code>src/console/</code>. Any code that depends on a browser (specifically, it expects <code>window</code> to be the global or <code>document</code> is present) should live in <code>src/html/</code>.</p> <div class="pilwrap" id="Install Dependencies"> <h3> <a href="#Install Dependencies" name="Install Dependencies" class="pilcrow">¶</a> Install Dependencies</h3> </div> <p>Jasmine Core relies on Ruby and Node.js.</p> <p>To install the Ruby dependencies, you will need Ruby, Rubygems, and Bundler available. Then:</p> <div class="highlight"><pre><code><span class="nx">$</span> <span class="nx">bundle</span> </code></pre></div> <p>...will install all of the Ruby dependencies.</p> <p>To install the Node dependencies, you will need Node.js, Npm, and <a href="http://gruntjs.com/">Grunt</a>, the <a href="https://github.com/gruntjs/grunt-cli">grunt-cli</a> and ensure that <code>grunt</code> is on your path.</p> <div class="highlight"><pre><code><span class="nx">$</span> <span class="nx">npm</span> <span class="nx">install</span> <span class="o">--</span><span class="nx">local</span> </code></pre></div> <p>...will install all of the node modules locally. If when you run</p> <div class="highlight"><pre><code><span class="nx">$</span> <span class="nx">grunt</span> </code></pre></div> <p>...you see that JSHint runs your system is ready.</p> <div class="pilwrap" id="How to write new Jasmine code"> <h3> <a href="#How to write new Jasmine code" name="How to write new Jasmine code" class="pilcrow">¶</a> How to write new Jasmine code</h3> </div> <p>Or, How to make a successful pull request</p> <ul> <li><em>Do not change the public interface</em>. Lots of projects depend on Jasmine and if you aren't careful you'll break them</li> <li><em>Be environment agnostic</em> - server-side developers are just as important as browser developers</li> <li><em>Be browser agnostic</em> - if you must rely on browser-specific functionality, please write it in a way that degrades gracefully</li> <li><em>Write specs</em> - Jasmine's a testing framework; don't add functionality without test-driving it</li> <li><em>Write code in the style of the rest of the repo</em> - Jasmine should look like a cohesive whole</li> <li><em>Ensure the <em>entire</em> test suite is green</em> in all the big browsers, Node, and JSHint - your contribution shouldn't break Jasmine for other users</li> </ul> <p>Follow these tips and your pull request, patch, or suggestion is much more likely to be integrated.</p> <div class="pilwrap" id="Running Specs"> <h3> <a href="#Running Specs" name="Running Specs" class="pilcrow">¶</a> Running Specs</h3> </div> <p>Jasmine uses the <a href="http://github.com/pivotal/jasmine-gem">Jasmine Ruby gem</a> to test itself in browser.</p> <div class="highlight"><pre><code><span class="nx">$</span> <span class="nx">rake</span> <span class="nx">jasmine</span> </code></pre></div> <p>...and then visit <code>http://localhost:8888</code> to run specs.</p> <p>Jasmine uses Node.js with a custom runner to test outside of a browser.</p> <div class="highlight"><pre><code><span class="nx">$</span> <span class="nx">grunt</span> <span class="nx">execSpecsInNode</span> </code></pre></div> <p>...and then the results will print to the console. All specs run except those that expect a browser (the specs in <code>spec/html</code> are ignored).</p> <div class="pilwrap" id="Before Committing or Submitting a Pull Request"> <h2> <a href="#Before Committing or Submitting a Pull Request" name="Before Committing or Submitting a Pull Request" class="pilcrow">¶</a> Before Committing or Submitting a Pull Request</h2> </div> <ol> <li>Ensure all specs are green in browser <em>and</em> node</li> <li>Ensure JSHint is green with <code>grunt jshint</code></li> <li>Build <code>jasmine.js</code> with <code>grunt buildDistribution</code> and run all specs again - this ensures that your changes self-test well</li> </ol> <div class="pilwrap" id="Submitting a Pull Request"> <h2> <a href="#Submitting a Pull Request" name="Submitting a Pull Request" class="pilcrow">¶</a> Submitting a Pull Request</h2> </div> <ol> <li>Revert your changes to <code>jasmine.js</code> and <code>jasmine-html.js</code><ul> <li>We do this because <code>jasmine.js</code> and <code>jasmine-html.js</code> are auto-generated (as you've seen in the previous steps) and accepting multiple pull requests when this auto-generated file changes causes lots of headaches.</li> </ul> </li> <li>When we accept your pull request, we will generate these files as a separate commit and merge the entire branch into master.</li> </ol> <p>Note that we use Travis for Continuous Integration. We only accept green pull requests.</p> </div> </div> </body> </html>