JavaScript: jQuery Bug Fixing Guide

This article describes processes and policies that are no longer in use. It’s preserved in its entirety for historic record only.

If you’ve ever been interested in contributing to jQuery, but simply had no idea how to get started, I’ve created the following jQuery Bug Fixing Guide to walk through the steps of fixing bugs and contributing your fixes to the jQuery core. If bug fixing is not your thing, don’t worry, all of these tips apply to new features and enhancements as well! This guide was originally published on the jQuery Blog.

So what are you waiting for?

jquery-patching-tips.sh

# Tips for jQuery Bug Patching

# There are some assumptions made here, one being that you're
# set up with some form of "localhost" http server and that it's running.
#  - http://www.mamp.info/en/mamp/
#  - sudo apt-get install apache2

# Get it running:
# On Mac:

  $ python -m SimpleHTTPServer

# On Linux:

  $ sudo /etc/init.d/apache2 start

# Remy Sharp has a created a useful node based web server for use wherever node.js is available:

  https://github.com/remy/servedir


# If you do not have git installed, check these out:
#  - http://help.github.com/mac-git-installation/
#  - http://help.github.com/linux-git-installation/


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

#  - http://nodejs.org/#download
#  - http://nodejs.org/#build
#
# Specifically you'll probably end up doing something like this:


  $ git clone https://github.com/joyent/node.git

  $ cd node

  $ ./configure

  $ make

  $ sudo make install

# With homebrew on OSX, you can also:

  $ brew install node

# 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

# I like to run "make clean" before any bug fixing sessions
# This ensures that you're running the most recent Sizzle and QUnit


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


  # Linux
  $ google-chrome http://localhost/jquery/test

  # Mac
  $ open http://localhost/jquery/test


# Success! You just built and tested jQuery!




# Fixing 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_####

# Open up files and make changes

# Open up the corresponding /test/unit/?????.js and add unit tests

# 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, enhancement, whatevs. Fixes #####"

# For a multiple line commit message, leave off the `-m "description"`.
# You will then be led into vi 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




# 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.





# 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 follwing examples assume you're working on a
# local repo, hosted on your localhost server.


# Example:

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

or default MAMP:

http://localhost:8888/test/?filter=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!!!
# jQuery supports the following:


** Supported Browsers :

Chrome Current - 1
Firefox 3.6.x, 5.0.x, 6.0.x
IE 6, 7, 8, 9
Safari 5.0.x
Opera Current - 1



# Feel free to add YOUR tips in the comment section below!