docs/changes.html

   1 <!--#include virtual="header.html" -->
   2
   3 <style type="text/css">
   4   pre {
   5     margin-top: 5px;
   6     margin-bottom: 5px;
   7   }
   8   ol > li { padding: 5px; }
   9 </style>
  10
  11 <h2>Guide to making dygraphs changes</h2>
  12
  13 <p>So you've made a change to dygraphs and would like to contribute it back
  14 to the open source project. Wonderful!</p>
  15
  16 <p>This is a step-by-step guide explaining how to do it.</p>
  17
  18 <h3>dygraphs style</h3>
  19 <p>First of all, please try to follow the style of the existing dygraphs
  20 code. This will make the review process go much more smoothly.<p>
  21
  22 <p>A few salient points:</p>
  23 <ol>
  24   <li>We try to adhere to Google's <a
  25     href="http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml">
  26     JS style guide</a> and would appreciate it if you try to as well. This
  27   means:
  28   <ul>
  29     <li>No tabs! Indent using two spaces.
  30     <li>Use camelCase for variable and function names.
  31     <li>Limit lines to 80 characters.
  32   </ul>
  33
  34   <li>Please run 'lint.sh' to see if you've introduced any new violations.
  35
  36   <li>If you've added a new feature, add a test for it (in the tests/
  37   directory) or a gallery entry.
  38
  39   <li>If you've added an option, document it in
  40   dygraph-options-reference.js. You'll get lots of warnings if you don't.
  41
  42   <li>If you've fixed a bug or added a feature, add an auto_test for
  43   it.<br/>
  44   This ensures that we won't inadvertently break your feature in the
  45   future. To do this, either add to an existing auto_test in
  46   auto_tests/tests or run
  47   <code>auto_tests/misc/new-test.sh your-test-name</code> to
  48   create a new one. There are two easy ways to run tests:
  49   <ul>
  50   <li>You can run your auto_test in any browser by visiting
  51   <code>auto_tests/misc/local.html</code>. This allows you to debug your
  52   test, or test against a specific browser.
  53   <li>You can run your auto_test on the command-line by running
  54   <code>./test.sh</code>. (It requires installing
  55   <a href="http://phantomjs.org">phantomjs</a> on your computer.)
  56   </ul>
  57 </ol>
  58
  59 <h3>Sending a Pull Request</h3>
  60
  61 <p>dygraphs is hosted on github, which uses a "pull request" model. They
  62 have a good writeup <a
  63   href="http://help.github.com/send-pull-requests/">here</a>. These
  64 instructions discuss dygraphs more specifically.</p>
  65
  66 <p>The list of steps may look a bit daunting, but it's not too bad,
  67 especially if you have any familiarity with git or github. If you run into
  68 any problems while following the instructions, feel free to contact
  69 dygraphs-users.</p>
  70
  71 <p>Why not just take patches? This process means less work for me (the
  72 maintainer) and it also results in your name appearing in the list of
  73 dygraphs commits. This lets you take credit for your work.</p>
  74
  75 <ol>
  76   <li>Create an account on <a href="http://github.com">github</a>. This is
  77   free, painless and will let you claim credit for your changes.
  78
  79   <li>Install git. github has a good writeup <a
  80     href="http://help.github.com/git-installation-redirect">here</a>.
  81
  82   <li>Create a fork of the dygraphs repository on github by
  83   clicking <a href="https://github.com/danvk/dygraphs">this link</a> and
  84   then the "Fork" button.
  85
  86   <li>You should see a URL along the lines of
  87   <code>git@github.com:yourname/dygraphs.git</code><br/>Copy this, open up a
  88   terminal and run<br/>
  89   <pre>git clone git@github.com:yourname/dygraphs.git</pre> This
  90   pulls the dygraphs code down onto your local disk.
  91
  92   <li>cd into the dygraphs directory and make your changes.<br/>
  93   If you've already got them somewhere else, just copy them over.<br/>
  94
  95   <li>Be a good citizen! Make sure your code follows the guidelines
  96   above.<br/>
  97     You'll have to do this before we accept your changes, so you may as well
  98     do it now
  99
 100   <li>Commit your changes locally: run
 101     <pre>git add .
 102 git commit</pre>
 103   Type in a description of your change. This will
 104   eventually appear in the dygraphs <a
 105     href="https://github.com/danvk/dygraphs/commits/master">commit list</a>.
 106
 107   <li>Push your changes to github by running <pre>git push</pre>This will
 108     send your changes to your forked repository on github.
 109
 110   <li>Go to your fork of dygraphs on github (i.e.
 111   github.com/yourname/dygraphs).<br/>
 112   Click the "Pull Request" button.<br/>
 113   This will send me an email with a pointer to your changes.
 114
 115   <li>We'll review your changes and (unless your code is perfect!) give you
 116   some feedback. Make these suggested changes in your local git client and
 117   re-run "git commit" and "git push" so that we can see them.
 118
 119   <li>Once your change is ready, we'll pull it into the main dygraphs
 120   repository and publish it to the web.
 121 </ol>
 122
 123 <!--#include virtual="footer.html" -->