[dygraphs.git] / docs / changes.html

<!DOCTYPE html>
<html>
  <head>
    <meta http-equiv="X-UA-Compatible" content="IE=EmulateIE7; IE=EmulateIE9">
    <title>Guide to making dygraphs changes</title>
    <style type="text/css">
      code {
        white-space: pre;
        border: 1px dashed black;
        display: inline-block;
        margin-left: 5px;
        margin-right: 5px;
        padding: 2px;
      }
      pre  {
        white-space: pre;
        border: 1px dashed black;
        padding: 5px;
      }
      body { max-width: 800px; }
      ol > li { padding: 5px; }
    </style>
  </head>
  <body>
    <h2>Guide to making dygraphs changes</h2>

    <p>So you've made a change to dygraphs and would like to contribute it back
    to the open source project. Wonderful!</p>
    
    <p>This is a step-by-step guide explaining how to do it.</p>

    <h3>dygraphs style</h3>
    <p>First of all, please try to follow the style of the existing dygraphs
    code. This will make the review process go much more smoothly.<p>

    <p>A few salient points:</p>
    <ol>
      <li> I try to adhere to Google's <a
        href="http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml">
        JS style guide</a> and would appreciate it if you try to as well. This
      means:
      <ul>
        <li>No tabs! Indent using two spaces.
        <li>Use camelCase for variable and function names.
        <li>Limit lines to 80 characters.
      </ul>

      <li>Please run 'lint.sh' to see if you've introduced any new violations.

      <li>If you've added a new feature, add a test for it (in the tests/
      directory) or a gallery entry.

      <li>If you've added an option, document it in
      dygraph-options-reference.js. You'll get lots of warnings if you don't.

      <li>If you've fixed a bug or added a feature, add an auto_test for
      it.<br/>
      This ensures that we won't inadvertently break your feature in the
      future. To do this, either add to an existing auto_test in
      auto_tests/tests or run
      <code>auto_tests/misc/new-test.sh your-test-name</code> to
      create a new one. There are two easy ways to run tests:
      <ul>
      <li>You can run your auto_test in any browser by visiting
      <code>auto_tests/misc/local.html</code>. This allows you to debug your
      test, or test against a specific browser.
      <li>You can run your auto_test on the command-line by running
      <code>./test.sh</code>. (It requires installing
      <a href="http://phantomjs.org">phantomjs</a> on your computer.)
      </ul>
    </ol>

    <h3>Sending a Pull Request</h3>

    <p>dygraphs is hosted on github, which uses a "pull request" model. They
    have a good writeup <a
      href="http://help.github.com/send-pull-requests/">here</a>. These
    instructions discuss dygraphs more specifically.</p>

    <p>The list of steps may look a bit daunting, but it's not too bad,
    especially if you have any familiarity with git or github. If you run into
    any problems while following the instructions, feel free to contact
    dygraphs-users.</p>

    <p>Why not just take patches? This process means less work for me (the
    maintainer) and it also results in your name appearing in the list of
    dygraphs commits. This lets you take credit for your work.</p>

    <ol>
      <li>Create an account on <a href="http://github.com">github</a>. This is
      free, painless and will let you claim credit for your changes.

      <li>Install git. github has a good writeup <a
        href="http://help.github.com/git-installation-redirect">here</a>.

      <li>Create a fork of the dygraphs repository on github by
      clicking <a href="https://github.com/danvk/dygraphs">this link</a> and
      then the "Fork" button.

      <li>You should see a URL along the lines of
      <code>git@github.com:yourname/dygraphs.git</code><br/>Copy this, open up a
      terminal and run<br/>
      <pre>git clone git@github.com:yourname/dygraphs.git</pre> This
      pulls the dygraphs code down onto your local disk.

      <li>cd into the dygraphs directory and make your changes.<br/>
      If you've already got them somewhere else, just copy them over.<br/>

      <li>Be a good citizen! Make sure your code follows the guidelines
      above.<br/>
        You'll have to do this before I accept your changes, so you may as well
        do it now

      <li>Commit your changes locally: run
        <pre>git add .
git commit</pre>
      Type in a description of your change. This will
      eventually appear in the dygraphs <a
        href="https://github.com/danvk/dygraphs/commits/master">commit list</a>.

      <li>Push your changes to github by running <pre>git push</pre>This will
        send your changes to your forked repository on github.

      <li>Go to your fork of dygraphs on github (i.e.
      github.com/yourname/dygraphs).<br/>
      Click the "Pull Request" button.<br/>
      This will send me an email with a pointer to your changes.

      <li>I'll review your changes and (unless your code is perfect!) give you
      some feedback. Make these suggested changes in your local git client and
      re-run "git commit" and "git push" so that I can see them.

      <li>Once your change is ready, I'll pull it into the main dygraphs
      repository and publish it to the web.
    </ol>

  <!-- Google Analytics -->
<script type="text/javascript">
  var _gaq = _gaq || [];
  _gaq.push(['_setAccount', 'UA-769809-2']);
  _gaq.push(['_trackPageview']);
  (function() {
    var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
    ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
    var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
  })();
</script>
  </body>
</html>
Commit	Line	Data
	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>