Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 217 lines (121 sloc) 8.097 kB
b4d23e4 @rwaldron CONTRIBUTING.md: adds top header
rwaldron authored
1 # Contributing to jQuery
3cb36f7 @rwaldron Initial draft of CONTRIBUTING.md
rwaldron authored
2
42dd6b1 @rwaldron Second draft of CONTRIBUTING.md
rwaldron authored
3 1. [Getting Involved](#getting-involved)
1474c06 @rwaldron CONTRIBUTING.md: more contents links
rwaldron authored
4 2. [Discussion](#discussion)
5 3. [How To Report Bugs](#how-to-report-bugs)
6 4. [Core Style Guide](#jquery-core-style-guide)
7 5. [Tips For Bug Patching](#tips-for-jquery-bug-patching)
3cb36f7 @rwaldron Initial draft of CONTRIBUTING.md
rwaldron authored
8
9
10
42dd6b1 @rwaldron Second draft of CONTRIBUTING.md
rwaldron authored
11 ## Getting Involved
12
13 There are a number of ways to get involved with the development of jQuery core. Even if you've never contributed code to an Open Source project before, we're always looking for help identifying bugs, writing and reducing test cases and documentation.
14
15 This is the best way to contribute to jQuery core. Please read through the full guide detailing [How to Report Bugs](#How-to-Report-Bugs).
16
17 ## Discussion
18
19 ### Forum and IRC
20
c3b1367 @callumacrae Fixes to contributing.md. Closes gh-931
callumacrae authored
21 The jQuery core development team frequently tracks posts on the [jQuery Development Forum](http://forum.jquery.com/developing-jquery-core). If you have longer posts or questions please feel free to post them there. If you think you've found a bug please [file it in the bug tracker](#How-to-Report-Bugs).
42dd6b1 @rwaldron Second draft of CONTRIBUTING.md
rwaldron authored
22
c3b1367 @callumacrae Fixes to contributing.md. Closes gh-931
callumacrae authored
23 Additionally most of the jQuery core development team can be found in the [#jquery-dev](http://webchat.freenode.net/?channels=jquery-dev) IRC channel on irc.freenode.net.
42dd6b1 @rwaldron Second draft of CONTRIBUTING.md
rwaldron authored
24
25 ### Weekly Status Meetings
26
27 Every week (unless otherwise noted) the jQuery core dev team has a meeting to discuss the progress of current work and to bring forward possible new blocker bugs for discussion.
28
29 The meeting is held in the [#jquery-meeting](http://webchat.freenode.net/?channels=jquery-meeting) IRC channel on irc.freenode.net at [Noon EST](http://www.timeanddate.com/worldclock/fixedtime.html?month=1&day=17&year=2011&hour=12&min=0&sec=0&p1=43) on Mondays.
30
31 [Past Meeting Notes](https://docs.google.com/document/d/1MrLFvoxW7GMlH9KK-bwypn77cC98jUnz7sMW1rg_TP4/edit?hl=en)
32
33
34 ## How to Report Bugs
35
36 ### Make sure it is a jQuery bug
37
38 Many bugs reported to our bug tracker are actually bugs in user code, not in jQuery code. Keep in mind that just because your code throws an error and the console points to a line number inside of jQuery, this does *not* mean the bug is a jQuery bug; more often than not, these errors result from providing incorrect arguments when calling a jQuery function.
39
c3b1367 @callumacrae Fixes to contributing.md. Closes gh-931
callumacrae authored
40 If you are new to jQuery, it is usually a much better idea to ask for help first in the [Using jQuery Forum](http://forum.jquery.com/using-jquery) or the [jQuery IRC channel](http://webchat.freenode.net/?channels=%23jquery). You will get much quicker support, and you will help avoid tying up the jQuery team with invalid bug reports. These same resources can also be useful if you want to confirm that your bug is indeed a bug in jQuery before filing any tickets.
42dd6b1 @rwaldron Second draft of CONTRIBUTING.md
rwaldron authored
41
42
43 ### Disable any browser extensions
44
45 Make sure you have reproduced the bug with all browser extensions and add-ons disabled, as these can sometimes cause things to break in interesting and unpredictable ways. Try using incognito, stealth or anonymous browsing modes.
46
47
48 ### Try the latest version of jQuery
49
50 Bugs in old versions of jQuery may have already been fixed. In order to avoid reporting known issues, make sure you are always testing against the [latest build](http://code.jquery.com/jquery.js).
51
52 ### Try an older version of jQuery
53
54 Sometimes, bugs are introduced in newer versions of jQuery that do not exist in previous versions. When possible, it can be useful to try testing with an older release.
55
56 ### Reduce, reduce, reduce!
57
c3b1367 @callumacrae Fixes to contributing.md. Closes gh-931
callumacrae authored
58 When you are experiencing a problem, the most useful thing you can possibly do is to [reduce your code](http://webkit.org/quality/reduction.html) to the bare minimum required to reproduce the issue. This makes it *much* easier to isolate and fix the offending code. Bugs that are reported without reduced test cases take on average 9001% longer to fix than bugs that are submitted with them, so you really should try to do this if at all possible.
42dd6b1 @rwaldron Second draft of CONTRIBUTING.md
rwaldron authored
59
60 ## jQuery Core Style Guide
61
62 See: [jQuery Core Style Guide](http://docs.jquery.com/JQuery_Core_Style_Guidelines)
63
64 ## Tips For Bug Patching
65
66
67 ### Environment: localhost w/ PHP, Node & Grunt
68
69 Starting in jQuery 1.8, a newly overhauled development workflow has been introduced. In this new system, we rely on node & gruntjs to automate the building and validation of source code—while you write code.
70
71 The Ajax tests still depend on PHP running locally*, so make sure you have the following installed:
72
73 * Some kind of localhost server program that supports PHP (any will do)
74 * Node.js
75 * NPM (comes with the latest version of Node.js)
76 * Grunt (install with: `npm install grunt -g`
77
78
79 Maintaining a list of platform specific instructions is outside of the scope of this document and there is plenty of existing documentation for the above technologies.
80
81 * The PHP dependency will soon be shed in favor of an all-node solution.
82
83
84 ### Build a Local Copy of jQuery
85
86 Create a fork of the jQuery repo on github at http://github.com/jquery/jquery
87
88 Change directory to your web root directory, whatever that might be:
89
90 ```bash
91 $ cd /path/to/your/www/root/
92 ```
93
94 Clone your jQuery fork to work locally
95
96 ```bash
97 $ git clone git@github.com:username/jquery.git
98 ```
99
100 Change directory to the newly created dir jquery/
101
102 ```bash
103 $ cd jquery
104 ```
105
106 Add the jQuery master as a remote. I label mine "upstream"
107
108 ```bash
109 $ git remote add upstream git://github.com/jquery/jquery.git
110 ```
111
112 Get in the habit of pulling in the "upstream" master to stay up to date as jQuery receives new commits
113
114 ```bash
115 $ git pull upstream master
116 ```
117
118 Run the Grunt tools:
119
120 ```bash
121 $ grunt && grunt watch
122 ```
123
124 Now open the jQuery test suite in a browser at http://localhost/test. If there is a port, be sure to include it.
125
126 Success! You just built and tested jQuery!
127
128
c3b1367 @callumacrae Fixes to contributing.md. Closes gh-931
callumacrae authored
129 ### Fix a bug from a ticket filed at bugs.jquery.com:
42dd6b1 @rwaldron Second draft of CONTRIBUTING.md
rwaldron authored
130
131 **NEVER write your patches to the master branch** - it gets messy (I say this from experience!)
132
133 **ALWAYS USE A "TOPIC" BRANCH!** Like so (#### = the ticket #)...
134
135 Make sure you start with your up-to-date master:
136
137 ```bash
138 $ git checkout master
139 ```
140
141 Create and checkout a new branch that includes the ticket #
142
143 ```bash
144 $ git checkout -b bug_####
145
146 # ( Explanation: this useful command will:
147 # "checkout" a "-b" (branch) by the name of "bug_####"
148 # or create it if it doesn't exist )
149 ```
150
151 Now you're on branch: bug_####
152
153 Determine the module/file you'll be working in...
154
155 Open up the corresponding /test/unit/?????.js and add the initial failing unit tests. This may seem awkward at first, but in the long run it will make sense. To truly and efficiently patch a bug, you need to be working against that bug.
156
157 Next, open the module files and make your changes
158
159 Run http://localhost/test --> **ALL TESTS MUST PASS**
160
161 Once you're satisfied with your patch...
162
163 Stage the files to be tracked:
164
165 ```bash
166 $ git add filename
167 # (you can use "git status" to list the files you've changed)
168 ```
169
170
171 ( I recommend NEVER, EVER using "git add . " )
172
173 Once you've staged all of your changed files, go ahead and commit them
174
175 ```bash
176 $ git commit -m "Brief description of fix. Fixes #0000"
177 ```
178
179 For a multiple line commit message, leave off the `-m "description"`.
180
181 You will then be led into vi (or the text editor that you have set up) to complete your commit message.
182
183 Then, push your branch with the bug fix commits to your github fork
184
185 ```bash
186 $ git push origin -u bug_####
187 ```
188
189 Before you tackle your next bug patch, return to the master:
190
191 ```bash
192 $ git checkout master
193 ```
194
195
196
197 ### Test Suite Tips...
198
199 During the process of writing your patch, you will run the test suite MANY times. You can speed up the process by narrowing the running test suite down to the module you are testing by either double clicking the title of the test or appending it to the url. The following examples assume you're working on a local repo, hosted on your localhost server.
200
201 Example:
202
203 http://localhost/test/?filter=css
204
205 This will only run the "css" module tests. This will significantly speed up your development and debugging.
206
207 **ALWAYS RUN THE FULL SUITE BEFORE COMMITTING AND PUSHING A PATCH!**
208
209
210 ### jQuery supports the following browsers:
211
212 * Chrome Current-1
213 * Safari Current-1
214 * Firefox Current-1
215 * IE 6+
216 * Opera Current-1
Something went wrong with that request. Please try again.