jquery-patching-tips.md

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

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 [email protected]: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!

+1

git clone ==> git clone --recursive. It auto initializes & updates submodules.

oh wait. no submodules. nvm. ohwell.. #protip anyways.

I forgot to create a new feature branch before issuing a pull request, so my fork's master actually has a handful of commits that haven't been merged. They might never be, who knows. If you've run into this issue and want to create a new feature branch in order to issue a new pull request, without deleting your repo and doing things all over again, you should be able to follow these steps.

First, you need to find the SHA of a commit that predates any of your unmerged commits. Do this, and look for the most recent commit that isn't yours. That's probably the one you want. The SHA is the 7 characters of nonsense at the beginning of that line.

git checkout master && git log --pretty=format:"%h %ae, %ar: %s"

After you have the SHA, it's a simple matter of creating your branch from that commit, then pulling from the upstream repo. This assumes you've already defined upstream as a remote.

git checkout -b your_branch commit_sha && git pull upstream master

At this point, everything in your new branch should be up-to-date and ready for editing.

git status will also display what branch you're currently working on.

Nice how to/help list, really useful.

Really awesome work putting this together.

This really helps in understanding the process. Thanks for sharing.

If you are running into an issue using the python -m SimpleHTTPServer (on Mac) with ajax: jQuery.ajax() modules then you may not have php installed. I alleviated this setting up MAMP and using the webroot supplied.

You can use brew install node to install node, too.

You could use servedir to set up the localhost HTTP server, too.