A revised version of the spec (sorry, I would have used reply-to but something went amiss with gmail and I've lost the original)

Regards,

Graeme

---

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

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

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

Operation Sequence - 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: Patches are placed in the patch stack in the order they are received - Run the configurable set of sanity checks on the raw patch. A typical example is the checkpatch.pl script which checks the patch for correct style - Perform a dummy git-apply of the patch onto the HEAD of the target repository with all patches already on the repositories 'patch stack' applied - Record the results of the sanity checks and git-apply against the patch

Operation Sequence - New patch which is part of a series: - As part 'New single stand-alone patch' NOTE: Patches within a series are added to the patch stack in the order specified in the series - Record patch as being part of a series

Operation Sequence - Summary patch of a series - Group all patches of the series under this patch

Operation Sequence - 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 the configurable set of sanity checks on the raw patch. A typical example is the checkpatch.pl script which checks the patch for correct style - Perform a dummy git-apply of the patch onto the HEAD of the target repository with all patches already on the repositories 'patch stack' applied - Record the results of the sanity checks and git-apply against the patch

The Patch Stack: The patch stack is a doubly linked-list of patches. The 'zeroth' patch is the HEAD of the associated git repository to which all subsequent patches on the stack are applied. The objective of the patch stack is to quickly visualise which patches pass some basic, pre-determined sanity checks. By performing these basic tests, the maintainers (and the community as a whole) is spared the trouble of wasting time on broken patches.

For reference, the first patch after the 'zeroth' patch is defined as being at the bottom of the stack.

There are two types of tests performed against each patch - Stand-alone and inter-dependent tests. <<Hmmm, 'static' and 'dynamic' ?>>

Stand-alone 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)

Inter-Dependent 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 inter-dependent 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 inter- dependent tests are re-run for each patch in the patch stack. When a patch fails an inter-dependent test, it may not be necessary to stop running the inter-dependent 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. Therefore, the patch is marked as being excluded from the inter-dependency chain.

The web interface (see below) will allow a user to clearly see which patches have passed all of the stand-alone and inter-dependent tests.

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 - Alter the order of patches within a patch stack - Move patches between patch stacks - Formally reject patches - Commit patches - Purge committed patches from the patch stack (garbage collection) - 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) - Re-run inter-dependent 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)