[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 "auto_tests/misc/new-test.sh your-test-name" to
      create a new one. You can run your auto_test in any browser by visiting
      auto_tests/misc/local.html.
    </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 "auto_tests/misc/new-test.sh your-test-name" to
	61	create a new one. You can run your auto_test in any browser by visiting
	62	auto_tests/misc/local.html.
	63	</ol>
	64
	65	<h3>Sending a Pull Request</h3>
	66
	67	<p>dygraphs is hosted on github, which uses a "pull request" model. They
	68	have a good writeup <a
	69	href="http://help.github.com/send-pull-requests/">here</a>. These
	70	instructions discuss dygraphs more specifically.</p>
	71
	72	<p>The list of steps may look a bit daunting, but it's not too bad,
	73	especially if you have any familiarity with git or github. If you run into
	74	any problems while following the instructions, feel free to contact
	75	dygraphs-users.</p>
	76
	77	<p>Why not just take patches? This process means less work for me (the
	78	maintainer) and it also results in your name appearing in the list of
	79	dygraphs commits. This lets you take credit for your work.</p>
	80
	81	<ol>
	82	<li>Create an account on <a href="http://github.com">github</a>. This is
	83	free, painless and will let you claim credit for your changes.
	84
	85	<li>Install git. github has a good writeup <a
	86	href="http://help.github.com/git-installation-redirect">here</a>.
	87
	88	<li>Create a fork of the dygraphs repository on github by
	89	clicking <a href="https://github.com/danvk/dygraphs">this link</a> and
	90	then the "Fork" button.
	91
	92	<li>You should see a URL along the lines of
	93	<code>git@github.com:yourname/dygraphs.git</code><br/>Copy this, open up a
	94	terminal and run<br/>
	95	<pre>git clone git@github.com:yourname/dygraphs.git</pre> This
	96	pulls the dygraphs code down onto your local disk.
	97
	98	<li>cd into the dygraphs directory and make your changes.<br/>
	99	If you've already got them somewhere else, just copy them over.<br/>
	100
	101	<li>Be a good citizen! Make sure your code follows the guidelines
	102	above.<br/>
	103	You'll have to do this before I accept your changes, so you may as well
	104	do it now
	105
	106	<li>Commit your changes locally: run
	107	<pre>git add .
	108	git commit</pre>
	109	Type in a description of your change. This will
	110	eventually appear in the dygraphs <a
	111	href="https://github.com/danvk/dygraphs/commits/master">commit list</a>.
	112
	113	<li>Push your changes to github by running <pre>git push</pre>This will
	114	send your changes to your forked repository on github.
	115
	116	<li>Go to your fork of dygraphs on github (i.e.
	117	github.com/yourname/dygraphs).<br/>
	118	Click the "Pull Request" button.<br/>
	119	This will send me an email with a pointer to your changes.
	120
	121	<li>I'll review your changes and (unless your code is perfect!) give you
	122	some feedback. Make these suggested changes in your local git client and
	123	re-run "git commit" and "git push" so that I can see them.
	124
	125	<li>Once your change is ready, I'll pull it into the main dygraphs
	126	repository and publish it to the web.
	127	</ol>
	128
	129	<!-- Google Analytics -->
	130	<script type="text/javascript">
	131	var _gaq = _gaq \|\| [];
	132	_gaq.push(['_setAccount', 'UA-769809-2']);
	133	_gaq.push(['_trackPageview']);
	134	(function() {
	135	var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
	136	ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
	137	var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
	138	})();
	139	</script>
	140	</body>
	141	</html>