[debian] where to document branch layout

[Russ Allbery]

Stefano Zacchiroli <zack at debian.org> writes:

> I take your word on this :-), ... but can I suggest to improve the
> wording of Policy 4.14 to make it clearer? As it is right now the
> wording is totally source package oriented. Hence, if one has a source
> package which is entirely VCS-free (as it is normal to be), the text
> describing README.source just does not apply, as the source package is
> totally unrelated to the used VCS. That's why I was puzzled and why I
> asked.

Hm, that's a good point.  I'm not sure.  It's possible that maintaining a
distinction between manipulating the output source package and
manipulating the revision control system is good.  I've documented more
details frequently on a team wiki page for the Debian package mantenance
team.

> A point of your notes is still obscure to me though. You wrote about
> using a tmp-branch merge to serialize merges when conflicts arises from
> multiple feature branches. I fail to understand if that implies that I
> can then serialize, by just invoking git format-patch appropriately on
> master, changes as separate patches one per feature branch or not.
> Actually I'm not convinced it is possible, as that way you are
> serializing merges, not all the past history of commits coming from
> different feature branches, am I missing something?

The system that I describe doesn't maintain any branches that are useful
targets for git format-patch.  You'll end up with a pile of merge commits
and other unuseful patches in your stack.

The best idea that I've seen for maintaining good branches for git
format-patch is to also maintain features on branches that are rebased
instead of merged against each new upstream.  This duplicates the change
in two branches, one that's merged and one that's rebased, but you can use
git rerere to automate resolution of the rebase and the merge using the
results of whichever you do first.  (This idea is from Manoj.)

I'm not actually doing this in practice right now; so far, I'm just using
git diff upstream..branch to generate patches to send to upstream, which
obviously isn't ideal since it doesn't include the commit message.

-- 
Russ Allbery (rra at stanford.edu)             <http://www.eyrie.org/~eagle/>