[U-Boot] RFC - PatchTrack Specification (revised)

[Graeme Russ]

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)