How to cope with patches sanely

[Manoj Srivastava]

On Sat, Jan 26, 2008 at 11:39:32PM +0100, Pierre Habouzit wrote:
> 
> Another thing is that people have the old habit to see the source
> package be the preferred form of modification for a Debian package.

        Hmm. This started off a train of thought. In one sense, one
 could see the source code for the binary package as the sources
 delivered by applying the diff.gz to the upstream tarball, and the rest
 merely tools to deliver the sources, somewhat like editors. I don't
 want to go down that debate, since the binary blob people would jump in
 and claim that the hardware editors creating the binary blobs are,
 ummm, editors.

        David Nusinow has criticized my methodology as delivering a
 mostly opaque diff.gz; and I have been thinking about that too. The
 criticism has merit; and I allowed myself to get distracted by the
 whole quilt subthread, which was a red herring. quilt introduces
 linearlization of patches, etc, and ordering, which were merely
 distractions.


        But the comment above by Pierre got me thinking: when someone
 reports a bug in my package, and I fix it, or when I add a whole new
 feature; I do not do it on the integration branch.  I do it on a new
 branch, dedicated to that series of fixes or the new feature, and the
 goal of the branch is to maintain a clean topic patch to feed
 upstream. I then post the same fix into the integration branch, easily
 done. So the modifications are being made in a topic branch -- but
 then, I ship only the integration branch (which is what the diff.gz
 represents) in the source package.

        So, in a very real sense, I do not ship the branch where I
 prefer to make the changes.

        Now, David had a point that people who need to make changes need
 to understand how to take the diff.gz apart, and understand what parts
 of the diff.gz correspond to which logical line of development.  This
 annotation of the diff lies in the topic branches; the integration
 branch has elided the annotation, in one sense. So, by only shipping
 the integration branch (as a diff.gz), I am eliding information that is
 present in my SCM, and not presenting that to the end user. This is not
 a good thing.

        Then it struck me: why not present the end users with the same
 environment and history that I have when I make changes? So, here are
 the goals of my proposal:

  A) All the branches that I use (the pure feature branches, the
     upstream branch, and the integration branch) should be made
     available to the users. This will give them the same environment I
     have, and thus they have the preferred place to make modifications.
  B) When people do dpkg-source -x, they should have a fully unpacked
     tree that is compiled, with no further action that needs to be
     taken
  C) In order to reconstitue all the other branches, no network
     connectivity should be required.  There a lot of people in the
     developing world that do not have a readily available network
     connection -- my solution must work with source DVD's
  D) No knowledge of my SCM should be required.  People should be able
     to construct the topic branches without knowing arch or git or bzr
     or Hg or what have you.

        Now, a lot of what I need is already present.
 1) the orig.tar.gz represents the upstream branch, exactly.
 2) the diff.gz + orig.tar.gz represents the integration branch,
    exactly.

        So the missing thing is the topic branches.
  3) I propose ./debian/branches/{TopicA,TopicB,TopicC}.diff.gz
     files. Each diff, applied to the orig.tar.gz , shall recreate for
     the interested user the corresponding branch in my development.

        Bingo. With this addition, every user that want to see where the
 integration branch comes from can examine each topic patch or topic
 branch. Each of these topic branches can then be compiled and
 experimented with.  Upstream can incorporate each of these topic
 patches, if they wish.

        Any end user who wishes to modify Topic branch C can, then,
 modify the topic branch, and apply the same delta to the integration
 branch, and they have done the same thing that I would do with the
 patch. In other words, they have the same work flow, and preferred
 means of modification, even if they do not know my SCM.

        People who do not care about independent lines of development
 can just ignore ./debian/branches, since that directory is never used
 in building, and is for human consumption.

        The downside, of course, is shipping the same patch twice, once
 in the diff.gz, and once in ./debian/branches/*.diff.gz.

        Comments welcome.

        manoj
-- 
"Laugh while you can, monkey-boy." Dr. Emilio Lizardo
Manoj Srivastava <srivasta at debian.org> <http://www.debian.org/~srivasta/>  
1024D/BF24424C print 4966 F272 D093 B493 410B  924B 21BA DABB BF24 424C