docs/changes.html

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