1## Contributing to Flot ##
2
3We welcome all contributions, but following these guidelines results in less
4work for us, and a faster and better response.
5
6### Issues ###
7
8Issues are not a way to ask general questions about Flot. If you see unexpected
9behavior but are not 100% certain that it is a bug, please try posting to the
10[forum](http://groups.google.com/group/flot-graphs) first, and confirm that
11what you see is really a Flot problem before creating a new issue for it.  When
12reporting a bug, please include a working demonstration of the problem, if
13possible, or at least a clear description of the options you're using and the
14environment (browser and version, jQuery version, other libraries) that you're
15running under.
16
17If you have suggestions for new features, or changes to existing ones, we'd
18love to hear them! Please submit each suggestion as a separate new issue.
19
20If you would like to work on an existing issue, please make sure it is not
21already assigned to someone else. If an issue is assigned to someone, that
22person has already started working on it. So, pick unassigned issues to prevent
23duplicated effort.
24
25### Pull Requests ###
26
27To make merging as easy as possible, please keep these rules in mind:
28
29 1. Submit new features or architectural changes to the *<version>-work*
30    branch for the next major release.  Submit bug fixes to the master branch.
31
32 2. Divide larger changes into a series of small, logical commits with
33    descriptive messages.
34
35 3. Rebase, if necessary, before submitting your pull request, to reduce the
36    work we need to do to merge it.
37
38 4. Format your code according to the style guidelines below.
39
40### Flot Style Guidelines ###
41
42Flot follows the [jQuery Core Style Guidelines](http://docs.jquery.com/JQuery_Core_Style_Guidelines),
43with the following updates and exceptions:
44
45#### Spacing ####
46
47Use four-space indents, no tabs.  Do not add horizontal space around parameter
48lists, loop definitions, or array/object indices. For example:
49
50```js
51    for ( var i = 0; i < data.length; i++ ) {  // This block is wrong!
52        if ( data[ i ] > 1 ) {
53            data[ i ] = 2;
54        }
55    }
56
57    for (var i = 0; i < data.length; i++) {  // This block is correct!
58        if (data[i] > 1) {
59            data[i] = 2;
60        }
61    }
62```
63
64#### Comments ####
65
66Use [jsDoc](http://usejsdoc.org) comments for all file and function headers.
67Use // for all inline and block comments, regardless of length.
68
69All // comment blocks should have an empty line above *and* below them. For
70example:
71
72```js
73    var a = 5;
74
75    // We're going to loop here
76    // TODO: Make this loop faster, better, stronger!
77
78    for (var x = 0; x < 10; x++) {}
79```
80
81#### Wrapping ####
82
83Block comments should be wrapped at 80 characters.
84
85Code should attempt to wrap at 80 characters, but may run longer if wrapping
86would hurt readability more than having to scroll horizontally.  This is a
87judgement call made on a situational basis.
88
89Statements containing complex logic should not be wrapped arbitrarily if they
90do not exceed 80 characters. For example:
91
92```js
93    if (a == 1 &&    // This block is wrong!
94        b == 2 &&
95        c == 3) {}
96
97    if (a == 1 && b == 2 && c == 3) {}  // This block is correct!
98```
99