Documentation

Tips for jQuery Bug Patching

From jQuery JavaScript Library

Jump to: navigation, search

Contents

[edit]

Install Apache, Git, and NodeJS

There are some assumptions made here, one being that you are set up with some form of "localhost" http server and that it's running.


On a Mac, you can run Apache via MAMP: http://www.mamp.info/en/mamp/

On Windows, you can run Apache via WAMP: http://www.wampserver.com/en/

(Each of those is a straightforward one-click installer)

On Linux, you can install Apache with the following command: 

 $ sudo apt-get install apache

Get it running: 

 # Mac: 
 $ python -m SimpleHTTPServer

 # Linux:
 $ sudo /etc/init.d/apache2 start

 # Windows
 Start > Programs > Wampserver >Start Wampserver

If you do not have git installed, check these out:

If you do not have NodeJS installed please download the code and follow the build instructions on your system:

Specifically you'll probably end up doing something like this: 

 $ git clone https://github.com/ry/node.git
 $ cd node
 $ ./configure
 $ make
 $ sudo make install
[edit]

Build a Local Copy of jQuery

Create a fork of the jQuery repo on github at http://github.com/jquery/jquery

Change directory to your web root directory, whatever that might be: 

 $ cd /path/to/your/www/root/

Clone your jQuery fork to work locally 

 $ git clone git@github.com:username/jquery.git

Change directory to the newly created dir jquery/ 

 $ cd jquery

Add the jQuery master as a remote. I label mine "upstream" 

 $ git remote add upstream git://github.com/jquery/jquery.git

Get in the habit of pulling in the "upstream" master to stay up to date as jQuery receives new commits 

 $ git pull upstream master

Build the jQuery source 

 $ make

It is a good idea to run make clean followed by make before any bug fixing sessions. This ensures that you're running the most recent Sizzle and QUnit as well.

Open the jQuery test suite in a browser (I use Google Chrome; change this to your preferred browser). 

 # Linux
 $ google-chrome http://localhost/test
 
 # Mac
 $ open http://localhost/test


Success! You just built and tested jQuery!

[edit]

Fix a bug from a ticket filed at bugs.jquery.com:

NEVER write your patches to the master branch - it gets messy (I say this from experience!)

ALWAYS USE A "TOPIC" BRANCH! Like so (#### = the ticket #)...

Make sure you start with your up-to-date master: 

 $ git checkout master

Create and checkout a new branch that includes the ticket # 

 $ git checkout -b bug_####
 
 # ( Explanation: this useful command will:
 # "checkout" a "-b" (branch) by the name of "bug_####"
 # or create it if it doesn't exist )

Now you're on branch: bug_####

Determine the module/file you'll be working in...

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.

Next, open the module files and make your changes

Run http://localhost/jquery/test --> ALL TESTS MUST PASS

Once you're satisfied with your patch...

Stage the files to be tracked: 

 $ git add filename
 
 # (you can use "git status" to list the files you've changed)

( I recommend NEVER, EVER using "git add . " )

Once you've staged all of your changed files, go ahead and commit them 

 $ git commit -m "Brief description of fix. Fixes #0000"

For a multiple line commit message, leave off the `-m "description"`.

You will then be led into vi (or the text editor that you have set up) to complete your commit message.

Then, push your branch with the bug fix commits to your github fork 

   $ git push origin -u bug_####

Before you tackle your next bug patch, return to the master: 

   $ git checkout master
[edit]

To send a Pull Request for your patch:

  • Go to http://github.com/you/jquery
  • Click "Switch Branches" and select the branch that has your patch.
  • Once the branch is loaded, click on "Pull Request".
  • Be sure to include the ticket #### in the subject, along with a brief description.


[edit]

Test Suite Tips...

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.

Example:

http://localhost/jquery/test/?css:

This will only run the "css" module tests. This will significantly speed up your development and debugging.

ALWAYS RUN THE FULL SUITE BEFORE COMMITTING AND PUSHING A PATCH!

[edit]

jQuery supports the following browsers:

  • Chrome Current-1
  • Safari 3+
  • Firefox 3.6, 4, 5
  • IE 6+
  • Opera Current-1
Retrieved from "http://docs.jquery.com/Tips_for_jQuery_Bug_Patching"