jQuery Mobile Bug Patching

jqm-patch.md

Tips for jQuery Mobile Bug Patching

Requirements:

PHP Web Server

Some common ones:

• Mac - MAMPP
• Mac, Windows - XAMPP
• Linux - Apache sudo apt-get install apache2 libapache2-mod-php5 php5 php5-common

Git

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

• http://help.github.com/mac-git-installation/
• http://help.github.com/linux-git-installation/

Get the Code

1. Open a terminal (command prompt)

2. Change directory (cd) to your web root directory, whatever that might be:

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

3. Clone your jQuery Mobile fork to work locally

   git clone git@github.com:username/jquery-mobile.git

4. Change directory to the newly created dir: jquery-mobile/

   cd jquery-mobile

5. Add the jQuery Mobile master repo as a remote. "upstream" is a good name for it

   git remote add upstream git://github.com/jquery/jquery-mobile.git

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

   git pull upstream master

7. (Mac/*Nix) Build the jQuery Mobile source

   make

(Windows) You will need someway to build makefiles

Testing Your Checkout

Open the jQuery Mobile test suite in the browser of your choice.

Navigate to http://localhost/jquery-mobile/ or whatever your jQuery Mobile folder is called.

If you see the jQuery Mobile Docs page, then this was a success! You just cloned and built jQuery Mobile!

Patching a Bug

1. Find a bug you think you can fix from the list at jQuery Mobile Issues

2. Follow the directions above to checkout a clone of the repository or navigate to your existing checkout

3. Create a new branch to work in:

   • Always use a branch to work in as working in master will get messy
   • Find the issue number in Github for the bug you want to fix. It will be 4 numbers long.
   • Make sure you start with your up-to-date master
     • git checkout master; git pull upstream master
   • Create and checkout a new branch that includes the ticket (issue_#### where #### is the 4 digit issue number )
     • git checkout -b issue_####
     • This will create a new branch (-b), if it does not exist yet, named issue_#### and then switches you into that branch (checkout)

4. Open up your favorite text editor and make the changes you want that will fix the issue referenced.

5. Run the unit tests to confirm that you have not broken anything.

   • Navigate to the http://localhost/jquery-mobile/tests/unit (or whatever your local checkout directory is called.
   • Ensure all tests still pass
   • Edit your code if it causes a test to fail

6. Commit your changes once you are done editing the files and the tests pass:

   • Stage the files to be tracked:
     • git add filename(s) You can use "git status" to list the files you have changed. I recommend NEVER, EVER using "git add . "
   • Once you have staged all of your changed files, go ahead and commit them:
     • git commit -m "Issue #####: Brief description of fix"
   • Then, push your branch with the bug fix commits to your github fork
     • git push origin -u issue_####

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

   • git checkout master

8. Submit a Pull Request to actually submit your patch:

   • Go to http://github.com/your-username/jquery-mobile
   • Click the branch switcher on the right and choose 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.
   • Submit the Pull Request

9. Congratulations, you just submitted your Patch! Thanks for your help.

Thanks to Rick Waldron for the original gist: http://docs.jquery.com/Tips_for_jQuery_Bug_Patching

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

Hi! Thanks, these notes were helpful.

It seems like this should include a note about accessing and running the test suite. I forked your gist and made a couple additions but wasn't sure how to pull-request a gist.

Updated to include testing in the patch process

Hi @eddiemonge!
Thanks for the notes! It helps a lot!
I'm on the way to clone my github repo to local (btw as you said, 102.40 MiB are a bit surprising)
After my first try to clone and open the docs and demos, some scripts and css-files could not be loaded,
because the index.html assumes that .php is the default suffix on my webserver. But it is not and I've added index.php to them.
Wouldn't it be better that this is the default?

@MauriceG do you mean your webserver servers .html files as .php files as its default? Or that it is looking for index.html and not index.php files as the default?

@eddiemonge, thanks for quick response!
Sorry for vague explanation. My webservers DirectoryIndex is index.html.
So for example <link rel="stylesheet" href="css/themes/default/" /> will not succeed, cause my server do not serve the index.php as directoryindex.

@MauriceG you will have to add DirectoryIndex index.html index.php to your httpd.conf to allow index.php files to be used.

Okay, @eddiemonge! Thanks a lot again! I will try. It's an Oracle IAS and i think this will not raise any issue.

@eddiemonge
Hi again!
At Patching a bug point 5 there is written to navigate to a localhost/jquery-mobile/test/ directory.
In my local clone there isn't a directory called "test".

@MauriceG Thanks for catching that typo

@eddiemonge
Thanks for that quick solution!
The test don't run. My webserver don't listen on standard-port 80.
The script changes the server-url (server:7778) to a full qualified url like server.domain.local/ without a port.
For example: http://server.domain.local/query-mobile/tests/unit/button
instead of http://server:7778/query-mobile/tests/unit/button/

@MauriceG does it? If it does, you should file a bug for that.

@eddiemonge
Yes, it seems, it does.
I've prepared my router to route external calls to port 7778 to my webserver at port 7778
and if i try to run the test suite from "outside", the console show, that the
test suite searches for my local server name ...
You can try at: http://deleted ...
Please give a response, so i can delete that reference to my server above.

@MauriceG I think its your redirect as I am seeing references to agoserv.ago.local in the requests. Like I said, you should probably file a bug with it as Im not too familiar with it.

First of all, many thanks for your time @eddiemonge!
I've "advised" my webserver to listen to port 80 too. The test suite works successfully.
I think, this "webserver with non-standard-port let's test-suite crash"-issue has time until post 1.0.
And it seems, it is an external script so may @jeresig take a look at this.
But something else: The test suite show me two errors but i didn't change any file...

Correction: I've started the test suite a second time and the failures disappear.

@eddiemonge
Hi, me again... I've created an issue #2845 to try to pull from my remote clone.
Then i've gone all the steps above and ... shesh ... i had a typo in my brief commit description.
I've decided to delete the remote-branch and have studied the github manual how to do that.
I've tried git branch -D origin/issue_2845 -r and the branch wasn't show anymore with git branch -r
but it was still existing at my online githup repo.
So I've tried git push git@github.com:MauriceG/jquery-mobile :issue_2845 and it had worked.
Then again I've created a branch with the same name but another description as before and pushed it online.
At my online repo now, the branch has the description from my first push.
Is this a github bug or what I've done wrong?

It might be a GH bug