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