[[PageOutline]]

= Contributing to the Qt Port of WebKit =

== Checking out the sources ==
Developers who wish to contribute to the port can check out the sources like so:
[http://gitorious.org/qtwebkit Gitorious.org] is hosting a [http://gitorious.org/qtwebkit public git repository] of the QtWebKit port.

{{{
git clone git://gitorious.org/webkit/webkit.git
}}}

 * Gitorious.org is experience a few hiccups lately. Prefer to clone it via ssh, as explained in this post: [http://qtwebkit.blogspot.com/2010/09/fatal-remote-end-hung-up-unexpectedly.html QtWebKit Developer Journal: fatal: The remote end hung up unexpectedly]

This is a git mirror of the WebKit SVN repository.

If you also want to track the staging branches for QtWebKit releases, do:

{{{
cd webkit
git remote add qtwebkit git://gitorious.org/+qtwebkit-developers/webkit/qtwebkit.git
git fetch qtwebkit
}}}

This repository has the QtWebKit staging branches and other branches specific to the QtWebKit port.

To see the remote branches you just fetched do:
{{{
git branch -r
}}}

For the tags simply do:
{{{
git tag
}}}

And to switch to a branch or a tag simply use {{{git checkout}}}


== Submitting a patch ==
When using a git repository to access the sources, the steps to submit a patch are roughly as follows. Please see the WebKit project's page about [http://webkit.org/coding/contributing.html contributing] for more information.
 * Make your changes
 * Add a [http://webkit.org/quality/testwriting.html layout test]
 * If you are using Git to create patches , read UsingGitWithWebKit#WebKitScriptsupportforGit
 * Run the {{{Tools/Scripts/check-webkit-style}}} script.
 * Run the {{{Tools/Scripts/prepare-ChangeLog}}} script to create an entry for your changes in each relevant ChangeLog file.
 * Edit the ChangeLog files reported by the prepare-ChangeLog script:
   * If you work on a task without bug report on bugs.webkit.org yet, create a bug report. Use the severity "Enhancement" if your patch is an improvement and not related to a bug.
   * Add a short description and paste the bug URL below it. Add an extra line and a detailed description if necessary.
   * Precede the short description with "[Qt]" if your patch is specific to the Qt port of WebKit.
   * The description text should be the same in all ChangeLog files.
   * Keep the "Reviewed by NOBODY (OOPS!)." line in the ChangeLog files, it will be edited by the bot or person that will commit your fix.
 * Do a {{{git diff > patchname.patch}}} to create your patch (use {{{--cached}}} if you first did a {{{git add}}} to put your changes in the git index). For detailed help, see UsingGitWithWebKit
 * Attach the patch to the bug report, set the {{{review}}} flag to '?' and the {{{commit-queue}}} flag to '?'
 * Wait :)

== Hacking on QtWebKit ==
All commits to QtWebKit are required to follow the [http://webkit.org/coding/coding-style.html WebKit coding style]. That includes qwebview(.h|cpp), qwebpage(.h|.cpp) and all others.

 * [wiki:"QtWebKitHacking" QtWebKit overview]
 * [wiki:"QtWebKitAPI" Process of contribution to QtWebKit's API]

== Information on Git for QtWebKit developers ==
 * [wiki:"UsingGitWithWebKit" Using Git with WebKit]
 * [http://ktown.kde.org/~zrusin/git/git-cheat-sheet-medium.png A Git cheat sheet]
 * [http://eagain.net/articles/git-for-computer-scientists/ An excellent article on Git for computer scientists]

== Communication ==
We use the regular webkit-dev mailing and IRC channels list to coordinate:

 * [http://lists.webkit.org/mailman/listinfo.cgi/webkit-qt webkit-qt Mailing List]
 * [http://lists.webkit.org/mailman/listinfo.cgi/webkit-dev webkit-dev Mailing List]
 * IRC: #qtwebkit at freenode
 * IRC: #webkit at freenode

=== Running the tests ===

See also:
 * QtWebKitTesting
 * [http://webkit.sed.hu/blog/20101028/qtwebkit-builder-and-tester-virtual-machine QtWebKit Builder and Tester Virtual Machine] (will save you from a lot of trouble)

==== Dependencies ====
You will need to install the following packages to run the layout tests:

 * Curl
 * Ruby 1.8 or greater
 * Apache 2
 * libapache2-mod-php5 (i.e. the PHP 5 Apache 2 module)

For your convenience, below are the commands needed to install these dependencies on popular linux distributions:

'''Ubuntu''':
{{{
sudo aptitude install curl ruby apache2 libapache2-mod-php5
}}}

'''Fedora''':
{{{
sudo yum install curl ruby httpd mod_ssl mod_php
}}}

==== Installing the layout test fonts/Using run-webkit-tests ====
To run the tests the normal WebKit layout test infrastructure is used. In addition you need a fixed set of fonts for testing. You can download them using Git from Gitorious:

{{{
git clone git://gitorious.org/qtwebkit/testfonts.git
}}}

Then you have to set the WEBKIT_TESTFONTS variable to point to the newly checked-out testfonts directory.

As the last step you can just run
{{{
run-webkit-tests
}}}
from the Tools/Scripts directory.

Individual tests can be run just directly using for example
{{{
run-webkit-tests LayoutTests/fast/forms/plaintext-mode-1.html
}}}

For debugging at test it may also be useful to run it directly in DumpRenderTree (with gdb):
{{{
WebKitBuild/Debug/bin/DumpRenderTree -v LayoutTests/fast/forms/plaintext-mode-1.html
}}}

The expected output can usually be found in the file with the same name as the test itself but with the .expected extension.

=== Building API Docs ===
Before you can build the API docs you need make sure to have Qt build from sources and run {{{make docs}}} in your Qt build directory once. This will ensure that the Qt API documentation is built and can be referenced from the QtWebKit docs and it will also ensure that qdoc (the tool that generates the API docs) is built.

To build the QtWebKit API docs simply run {{{make docs}}} in your build directory, i.e. {{{WebKitBuild/Release}}}. The output will be generated in HTML in the {{{doc/html}}} subdirectory.

== Obtaining Check-In Privileges ==
Contributors with a proven track record of good patch submissions and that have demonstrated an ability to work well with the community can obtain check-in privileges to the QtWebKit git repository.  

The various branches of the git repository mirror the branches in the [http://webkit.org/building/checkout.html upstream public webkit svn repository].  Patches that land on a branch in the git repository are not automatically pushed to the svn repository.  Patches intended for the svn repository must first be reviewed and then committed by developers with [http://webkit.org/coding/contributing.html sufficient privileges].

Patches that are not specific to the QtWebKit port of the webkit project should not be submitted to the git repository rather they should be contributed directly to the upstream public webkit svn repository. 

To obtain check in privileges to the git repository the contributor should inquire from one of the Administrator(s) of the [http://gitorious.org/+qtwebkit-developers qtwebkit-developers team.]

== Attic ==
 * [wiki:"QtWebKitTodo" TODO List]