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

[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)

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

[Wolfgang Denk]

Dear Graeme Russ,

In message <CALButCJXJE+mo_W5=kYT8btO4e36-i5ajmcGrE-cG0fyP1RgFw@mail.gmail.com> you wrote:
> 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)

http://www.denx.de/wiki/U-Boot/ToolsPatchTracking   updated.

Best regards,

Wolfgang Denk

-- 
DENX Software Engineering GmbH,     MD: Wolfgang Denk & Detlev Zundel
HRB 165235 Munich, Office: Kirchenstr.5, D-82194 Groebenzell, Germany
Phone: (+49)-8142-66989-10 Fax: (+49)-8142-66989-80 Email: wd at denx.de
You Earth people glorified organized violence  for  forty  centuries.
But you imprison those who employ it privately.
	-- Spock, "Dagger of the Mind", stardate 2715.1

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

[Graeme Russ]

Hi Wolfgang,

On Wed, Jul 25, 2012 at 4:41 AM, Wolfgang Denk <wd@denx.de> wrote:
> Dear Graeme Russ,
>
> In message <CALButCJXJE+mo_W5=kYT8btO4e36-i5ajmcGrE-cG0fyP1RgFw@mail.gmail.com> you wrote:
>> 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)
>
> http://www.denx.de/wiki/U-Boot/ToolsPatchTracking   updated.
>

Thanks - I've made a couple of minor tweaks

Regards,

Graeme

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

[Andy Pont]

Wolfgang wrote...

> > 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)
> 
> http://www.denx.de/wiki/U-Boot/ToolsPatchTracking   updated.

I have been and had a look at the specification that you have posted and am
happy to get my hands dirty helping with implement and test this.  

I know that a good proportion (possibly even all of it) could be implemented
in Python but is there a preference or consensus on what would be the best
language to do it in?

Regards,

Andy.

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

[Wolfgang Denk]

Dear Andy,

In message <004e01cd6a51$57d5ff70$0781fe50$@pont@sdcsystems.com> you wrote:
> 
> I have been and had a look at the specification that you have posted and am
> happy to get my hands dirty helping with implement and test this.  

Thanks in advance.

> I know that a good proportion (possibly even all of it) could be implemented
> in Python but is there a preference or consensus on what would be the best
> language to do it in?

Speaking for myself, I have no strict preferences.

It may make a lot of sense to look into existing code - much of what
we neeed (mail processing, collecting follow-ups, Acks etc.) is
already availabe in PatchWork - can we re-use this code instead of
re-inventing the wheel?

Best regards,

Wolfgang Denk

-- 
DENX Software Engineering GmbH,     MD: Wolfgang Denk & Detlev Zundel
HRB 165235 Munich, Office: Kirchenstr.5, D-82194 Groebenzell, Germany
Phone: (+49)-8142-66989-10 Fax: (+49)-8142-66989-80 Email: wd at denx.de
Computers are not intelligent.  They only think they are.

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

[Graeme Russ]

Hi Wolfgang,

On Wed, Jul 25, 2012 at 9:00 PM, Wolfgang Denk <wd@denx.de> wrote:
> Dear Andy,
>
> In message <004e01cd6a51$57d5ff70$0781fe50$@pont@sdcsystems.com> you wrote:
>>
>> I have been and had a look at the specification that you have posted and am
>> happy to get my hands dirty helping with implement and test this.
>
> Thanks in advance.

And a big thanks from me too :)

Before we 'dig in' and implement it, we really need to make sure that the
specification:

  a) Accurately describes something that will address the current problems
     we are experiencing in maintaining U-Boot
  b) Not, as far as we can currently tell, have scalability issues
  c) Be flexible enough to grow

>> I know that a good proportion (possibly even all of it) could be implemented
>> in Python but is there a preference or consensus on what would be the best
>> language to do it in?
>
> Speaking for myself, I have no strict preferences.

Me either

> It may make a lot of sense to look into existing code - much of what
> we neeed (mail processing, collecting follow-ups, Acks etc.) is
> already availabe in PatchWork - can we re-use this code instead of
> re-inventing the wheel?

Exactly. As Patchwork is Python, it makes sense to keep going with
Python for PatchTrack

However, I was thinking that PatchTrack would have a modular design and
implementation and that we should not restrict the language that the
modules are written in. Although, this may come later. In particular,
I can well imagine some of the 'static tests' being implemented as
simple shell scripts

Regards,

Graeme

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

[Marek Vasut]

Dear 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)

How does it surprise me ... superawesome google imap just crashed on me like a 
week ago, I finished syncing my emails today ...

[...]

> 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

You might want to actually create an mbox of all these stacked patches so people 
can download and apply them and rebase their patches on top of them.

[...]

> 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

Yes? Maybe this should be applied at the place where the old patch was, rather 
than on top.

[...]

> 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

Why not make committed like ... lavender or something </jab> ? :)

[...]
The rest sounds quite cool.

Best regards,
Marek Vasut

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

[Graeme Russ]

Hi Marek,

For future reference, please comment against:

Take a look at http://www.denx.de/wiki/U-Boot/ToolsPatchTracking

On 07/29/2012 01:15 PM, Marek Vasut wrote:
> Dear Graeme Russ,
> 
> You might want to actually create an mbox of all these stacked patches so people 
> can download and apply them and rebase their patches on top of them.

Under 'Web Interface':

"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)"

This could be an mbox file or an archive (.tgz) of patches

>> Operation Sequence - Revised version of existing patch

[snip]

> 
> Yes? Maybe this should be applied at the place where the old patch was, rather 
> than on top.

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

So yes, in place of the existing patch

> Why not make committed like ... lavender or something </jab> ? :)

:P

> 
> [...]
> The rest sounds quite cool.

Good :)

Regards,

Graeme

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

[Marek Vasut]

Dear Graeme Russ,

[...]

Are we getting anywhere with this?

Best regards,
Marek Vasut