[Gnu-arch-users] named patches, patch order, patch queue manager (was: the infinite thread)

[Tom Lord]

    > From: Davide Libenzi <address@hidden>

(Please don't quote so much. :-)

Your message points square at some very important issues.
There's a mix of "how to use arch" and "what new tools should be built
on top of arch":


    > [I like the idea of named patches: ]

    > $ ls -l
    > sched-fix-starvation-H1
    > vm-drop-oom-killer
    > fix-acpi-int-table
    > ...

    > $ cat ++patch-order
    > fix-acpi-int-table
    > sched-fix-starvation-H1
    > vm-drop-oom-killer
    > ...

    > It is also cleaner for a maintainer to say "your patch
    > sched-fix-starvation-H1 is crap" instad of "your patch-243 is
    > crap". 

Ok, two issues there: named patches and patch ordering.

This reply is pretty long just addressing named patches so I'll mostly
leave the (rather large) issue of managing patch ordering for later.

      contents:

        * named patches
        ** how to use arch for that
        ** what a patch queue manager should do


* named patches

** how to use arch for that

  There's more than one way to do it.  Here are two.

  I like the idea of named changes, too.  For scenarios like this, often
  (not always), that's what branch labels are for.

  For example, I would say a good name for "sched-fix-starvation-H1"
  might be:

        address@hidden

        fullname=$archive/linux--sched-fix-starvation-H1--2.6

  Why is that?   In general, I don't think you should expect
  "sched-fix-starvation-H1" to be a single revision -- it won't be
  patch-243 -- it may span several patches.

  In this example, suppose the maintainer said "that's crap; change it
  thusly...".  If the change is on it's own branch, you can just
  commit changes to that branch.

        linus' tree:            sched-fix-starvation-H1 tree:
        ------------            -----------------------------
        ...
        patch-I         -------> base-0

        ...                      ...

        patch-J                  patch-A

                                "Hey, want to merge this?"

        [looks at 
         delta(patch-J,patch-A)]
        "Nah, that's crap"      "Ok, I'll fix"

        ...                     ...

        patch-K  ~~~merge~~~~~> patch-B (catch up to recent mainline changes)

                                ....

                                patch-C

                                "Better?"

        [looks at
         delta(patch-K,patch-C)]
        "yes"

        ...

        patch-J  <~~~~merge~~~~ patch-C (still)



  In addition to letting you commit incremental corrections to the
  patch, this technique also allows you to star-merge.  For example,
  although the name "sched-fix-starvation-H1" suggests a fairly small
  change, let's pretend that it's a very large change that wants to be
  made in a series of smaller steps.  If it's desirable for Linus to
  merge just parts of the change early, at various milestones, then
  there's a situation of back-and-forth merging as Linus merges in
  milestones and you merge back to update the linus-tree baseline for
  work on sched-fix-starvation-H1.  Classic star-merge stuff.

  (In this case, if we consider the patch ordering in which
  sched-fix-starvation-H1 depends on fix-acpi-int-table, the branching
  pattern might be slightly different but I'm going to just gloss over
  that in this message.)

  That isn't the only way to do it, of course.  You don't _have_ to
  give the change its own branch.  Sometimes contributors to arch, for
  example, give a cherry-picking recipe.  As in: "change FOO is
  patch-X, patch-Y, and patch-Z".   In those cases, they usually just
  tell me: "FOO is patch-{X,Y,Z}" and that works out well enough.
  However, automation is good, so I've included some notes on a patch
  queue manager.

  The observation that "there's more than one way to do it" suggests
  that what is named by the name of a named patch doesn't map directly
  onto an arch name at all.   Instead, it's the name of a merge recipe
  that is expressed in terms of merge names.   For example, the name:

        sched-fix-starvation-H1

   might denote either the recipe:

        star merge from $archive/linux--sched-fix-starvation-H1--2.6

   or the recipe

        cherry pick from $archive/linux--devo--2.6
                patch-24
                patch-25
                patch-34
                patch-41

   or some other recipe entirely.

   So I agree that named patches are handy -- I just wonder if they
   aren't best seen as a layer _over_ arch.

   Alternatively, of course, Linus could have a policy: "All merge
   requests must be expressed as a single changeset".   But such a
   policy would be substituting contributor labor for automation 
   and entirely needless:


** what a patch queue manager should do

  What might a patch-queue-manager be in this case?  

  One way to imagine it is to picture an unholy tangle of web
  interfaces, GUI tools, email tools, bug trackers, and so forth with
  the net effect that:

  1) Linus has a "control panel" view showing changes people have 
     asked to have merged.   In this case it might say something like:

     * sched-fix-starvation-H1
       address@hidden
                Fix scheduler starvation
       archive: address@hidden  
       version: [linux--sched-fix-starvation-H1--2.6]   
         (mirrored, up-to-date 9/30/03 6:12)


       depends on: [fix-acpi-int-table]

       bug ids:  [#14834], [#24892]

       merges cleanly: [yes (linus--mainline--patch-1837)]
       fixes regressions: n/a
       [browse change] [browse thread] [prepare tree] [auto commit]

   Where the "[...]" items are links.

   Explanations:

        sched-fix-starvation-H1
                The name given to this merge request.

        address@hidden
                The submitter.

        address@hidden
                A link to the local status and options for that
                archive.  Linus might point-and-click to set up
                the local mirroring policy for the archive, 
                for example.

        [linux--sched-fix-starvation-H1--2.6]
                Similarly, a link to the local the mirroring
                options for that part of the archive.


        depends on: [fix-acpi-int-table]
                A list of other merge requests which are 
                prereqs for this one, with links to
                their control panel entries.

        [#14834] -- a link to an issue in a bug tracker that is 
                    purportedly addressed by this change

        merges cleanly: [yes ...]
                An indication that a batch process has attempted
                the merge and that, in this case, it merged without
                conflicts against a particular revision of mainline.

                The link leads to a page that would show a report
                of the conflicts and that allows one to kick the 
                batch process to try a merge against the latest.

        fixes regressions: n/a
                If any of the attached bug reports included links
                to regression tests, and the batch-merge was clean, 
                a batch process would run the regression tests for
                the merged result.  (In this case, the bugs don't 
                have associated tests, hence "n/a".)

        [browse change]
                A link to examine the effects of the merge

        [browse thread]
                A link to email messages about this merge request

        [prepare tree]
                A button that prepares a project tree with the merge
                performed.

        [auto commit]
                A button that just goes ahead and commits the merge.
                Of course for _some_ contributors, Linus himself for
                example, "auto commit" might be the default behavior
                with items showing up on the control-panel of pending
                merges only in the case of conflicts or regressions.


  2) Submitters have an interface of their own:

        Submit patch

        name: ________________

        summary: ________________

        source:
          archive: ________________
          version: ________________

        destination (if not linus--mainline--2.6):
          archive: ________________
          version: ________________

        merge type:  [ ] star-merge
                     [ ] cherry-pick
                         patches: ________________
                     [ ] sync tree
                     [ ] apply delta from baseline

        dependencies: ________________


     and their own control panel:

        [my patches] [submit patch] [withdraw patch]
        [my ongoing branches]

     etc.


  (The particular user interface described here is described only to
  communicate the underlying structure, of course.)


-t