Skip to main content.

Patch Tracking Tool

PatchTrack is designed to help alleviate some of the load from custodians managing an email based work flow accepting patches from a large community of contributors. PatchTrack does this by maintaining a database of patches which have been submitted to the mailing list. For each patch in the database, PatchTrack automatically runs a series of configurable tests (plugin framework?).

PatchTrack also provides a web-based interface. The web interface allows:

PatchTrack interfaces to the git source code management system

Core Concepts

PatchTrack monitors an email inbox which has been configured to receive emails from a group mailing list. PatchTrack scans incoming emails and determines, for each inbound email, if the email is:

Based upon the above determination of the incoming email, PatchTrack performs one of several 'Operation Sequences'

Determining the Email Type

The first action PatchTrack must take upon fetching an email from the configured mailbox is the content type of the email.

NOTE:: This may need to be done through some kind of plugin infrastructure - i.e. pass the body of the email to a plugin which extracts relevant information

Operation Sequences

New single stand-alone patch

New patch which is part of a series:

Summary patch of a series

Revised version of existing patch

The Patch Stack

The objective of the patch stack is to quickly visualise which patches pass the static and dynamic tests. By performing these basic tests, the maintainers (and the community as a whole) is spared the trouble of wasting time on broken patches.

The patch stack is a doubly linked-list of patches (the double-linking is to make it easier to insert, remove, and relocate patches within the stack)

Patches are initially added to the stack in the chronological order that they arrive at mailbox that PatchTrack is configured to monitor. Patches in a series are an exception - they are added to the stack in the same order that is specified in the patch title (i.e. if patch [PATCH 1/x] arrives in the mailbox after [PATCH 2/x], it will be inserted prior to [PATCH 2/x] rather than being simply added to the top of the stack)

The 'zeroth' patch is the HEAD of the associated git repository to which all subsequent patches on the stack are applied.

The first patch added to the patch stack is, by definition, the bottom of the stack.

The last patch added to the patch stack is, by definition, the top of the stack.

PatchTrack does not support the concept of branching and merging patch stacks (this is handled by the underlying git repositories)

Automated Patch Testing

A key feature of PatchTrack is the ability to automatically run a series of pre-configured tests against patches in the patch stack.

Each test is categorised as either a Static Test or a Dynamic Test

Static Tests

Static test are valid no matter where the patch is in the patch stack. Typically, these tests validate coding style, correct signed-off-by lines, compatible licensing (if present in the patch), etc. Stand-alone tests only need to be performed once per patch (and re-run when a new revision of the patch is submitted)

Dynamic Tests

Dynamic tests are tests for which the outcome will depend on the order of the patches in the patch-set (including the zeroth patch). The most typical dynamic test is the 'git-apply' test which checks that the patch will apply cleanly to the repository. Every time the patch stack is modified (patch added, removed, replaced, re-ordered, etc.) all dynamic tests are re-run for each patch in the patch stack. When a patch fails a dynamic test, it may not be necessary to stop running the dynamic tests on subsequent patches. For example, if the first patch in the stack fails to apply to the head of the repository, it is not necessarily true that all subsequent patches will also fail to apply. Therefore, the patch is marked as being excluded from the dyanmic chain.

The web interface (see below) will allow a user to: * Visualise which patches have passed each static and dynamic test * Override the result of the static and dynamic tests (in order to forcefully apply the patch)

Web Interface

In addition to processing inbound emails, PatchTrack includes web interface which allows a user to:

NOTE:
The patch stack is displayed as a series of rows in a table - One row per patch. The colour of the row can be configured for each patch state. For example, 'Acked' might be blue and 'Committed' white

The PatchTrack web interface allows an authenticated repository maintainer to:

Output

PatchTrack can be configured to generate email messages. Typical messages include:

While PatchTrack? can be configured to send emails to the mailing list, this is discouraged as it may produce an excessive amount of additional noise on the list