'''NOTE: This is a proposal in progress.'''

The purpose of QtWebKit gardening is to keep the Qt build and test bots green. It's a responsibility shared by all QtWebKit developers, though to be efficient you do need WebKit commit privileges.

There are four main tasks for the gardener:

 * Reacting to bot redness.
 * Maintaining the LayoutTests skip lists.
 * Maintaining the LayoutTests expected results.
 * Maintaining the Qt API tests.

Let's look at each one in detail...

== Reacting to bot redness ==

Pages to monitor:

 * http://build.webkit.org/
 * http://build.webkit.sed.hu/

Freenode IRC channels:

 * #qtwebkit
 * #webkit

== Maintaining the LayoutTests skip lists ==

These are currently the QtWebKit skip lists (black lists for LayoutTests):

 * LayoutTests/platform/qt/Skipped
 * LayoutTests/platform/qt-4.8/Skipped
 * LayoutTests/platform/qt-arm/Skipped
 * LayoutTests/platform/qt-linux/Skipped
 * LayoutTests/platform/qt-mac/Skipped
 * LayoutTests/platform/qt-win/Skipped
 * LayoutTests/platform/qt-wk2/Skipped

The "qt" list (LayoutTests/platform/qt/Skipped) is common and applies to all platforms. The other lists are for failures that are specific to that platform.

When a test starts failing, or a new test is added and fails on the Qt bot(s), the first thing to do is poking the person who caused the failure. If they are unavailable or insufficiently responsive, add the test to the appropriate Qt skip list and file a bug about it.

Regression bugs should have a title with format "REGRESSION(r######): [Qt] blah blah blah".
Examples:

 * REGRESSION(r12345): [Qt] New test fast/images/super-cute-cat.html failing.
 * REGRESSION(r67890): [Qt] Caused three tests in canvas/philip/ to fail.

The bugs should be marked with the keywords "Qt, QtTriaged, Regression". The CC list should include the developers who authored and reviewed the offending changeset.

== Maintaining the LayoutTests expected results ==

When new tests are added, it's sometimes necessary to have a platform-specific expected result, for instance if the output includes text metrics. These files live in LayoutTests/platform/qt*/foo/bar/baz-expected.txt and LayoutTests/platform/qt*/foo/bar/baz-expected.png (which corresponds to the test LayoutTests/foo/bar/baz.html)

For the text results, this is often as simple as running "webkit-patch rebaseline" and grabbing the results from the Qt bot. The screenshot (PNG) results are a little trickier, as they are currently not dumped by the bot, and need to be generated manually. These tests should be generated in an environment equivalent to that of the bot, i.e [http://webkit.sed.hu/blog/20101028/qtwebkit-builder-and-tester-virtual-machine the Q-BAT VM from Szeged].

== Maintaining the Qt API tests ==

The Qt API tests live in Source/WebKit/qt/tests/ and are part of the bot rotation. Although a failing API test currently does not make the bot flip red, it's important that we maintain the tests regardless.

The procedure is very similar to the LayoutTests, though we should have slightly higher tolerance for non-Qt WebKit developers inadvertently breaking our API tests. (This because our API takes some "artistic liberties" with regard to layering violations in more than a few places.)

Skip the failing test (or the failing sub-portion of the test if you are able to) by adding a [http://doc.qt.nokia.com/4.7/qtest.html#QSKIP] QSKIP() statement. Open a bug about the failure, "Qt, QtTriaged, Regression", CC'ing the appropriate people, and adding a comment with a reference to the bug# along with the QSKIP().