MediaWiki source for Tips for jQuery Bug Patching

tips-for-jquery-bug-patching.txt

=== Environment: localhost w/ PHP, Node & Grunt ===

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.

The Ajax tests still depend on PHP running locally*, so make sure you have the following installed:

* Some kind of localhost server program that supports PHP (any will do)
* Node.js
* NPM (comes with the latest version of Node.js)
* Grunt (install with: `npm install grunt -g`


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.

* The PHP dependency will soon be shed in favor of an all-node solution.

=== 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

Run the Grunt tools:
  
  $ grunt && grunt watch

Now open the jQuery test suite in a browser at http://localhost/test. If there is a port, be sure to include it.

Success! You just built and tested jQuery!

=== 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/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

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

Example:

http://localhost/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 browsers: ===

* Chrome Current-1
* Safari Current-1
* Firefox Current-1
* IE 6+
* Opera Current-1