You are here: DENX Home »  U-Boot » Tasks » ToolsPatchTracking

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:
  • Community members to view the status of patches submitted to the mailing list
  • Maintainers to perform various administrative actions against patches.

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:
  • A new single stand-alone patch
  • A new patch which is part of a series of patches (i.e. patch x of y)
  • A summary patch of a series of patches (i.e. patch 0 of y)
  • A revised version of an existing patch
  • A comment on an existing patch
  • A 'feedback tag' (Ack, Nack, Tested, etc.) for an existing patch (including the summary patch)

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

  • Determine which git repository the patch is intended to be applied to
  • Add the patch to the top of the 'patch stack' of the target repository (NOTE: Stand-alone patches are always placed in the patch stack in the order they are received)
  • Run each configured static test against the patch
  • Run each configured dynamic test against the patch
  • Record the results of the static and dynamic tests against the patch

New patch which is part of a series:

  • As per 'New single stand-alone patch'
    • Before running the dynamic tests, the patch is inserted into the patch stack according to the sequence numbering of the patch series
  • Record patch as being part of a series

Summary patch of a series

  • Group all patches of the series under this patch

Revised version of existing patch

  • Remove existing patch from patch stack
  • Insert new patch into patch stack at same location as the removed patch
  • Run each configured static test against the patch
  • Run each configured dynamic test against the patch
  • Record the results of the static and dynamic tests against the 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:
  • Visualise the state of the patch stack for a given repository
    • Passed sanity checks
    • Passed git-apply
    • Acked
    • Tested
    • Committed
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
  • View the meta data of each patch such as:
    • Patch Author
    • Date/Time patch was submitted
    • Next/Previous patches in the patch stack
    • Submitters of feedback tags
    • Result of each sanity check
    • Result of the git-apply
    • git commit id (for committed patches)
  • View the revision history of each patch
  • View the comments recorded against each patch
  • Download a patch set of all patches meeting a specific criteria (pass all stand-alone and inter-dependent tests and have been acked for example)

The PatchTrack web interface allows an authenticated repository maintainer to:
  • Alter the order of patches within a patch stack
  • Move patches between patch stacks
  • Formally accept or reject patches
  • Commit patches
  • Purge committed patches from the patch stack (garbage collection)
  • Re-run dyanmic tests using patches matching a specific criteria (all patches passing the stand-alone tests that have been acked for example)
  • Re-order patches based on specific criteria (move all patches which have passed stand-alone tests and have been acked to the bottom of the stack)

Output

PatchTrack can be configured to generate email messages. Typical messages include:
  • Notifying the author of the patch that particular Static or Dynamic test failed
  • Notifying the author that the patch has passed all Static and Dynamic tests
  • Notifying the author that the patch has been approved and is scheduled to be committed
  • Notifying the author that the patch has been commented on
  • Notifying the author that the patch has been Ack'd, Nack'd, Tested, etc.

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
Copyright © 2002-2022 by DENX Software Engineering GmbH ImprintTerms & ConditionsPrivacyFeedback
This website is using cookies. More info. That's Fine