headers
Stefano Zacchiroli | 15 Jul 20:35
Favicon

[debian] where to document branch layout

Hi all (again),
  with $DVCS the branch layout for a given package can become quite
complex, and AFAICS there is no agreed upon convention on branch layout.
Just the single choice of whether to use branches just for work and then
serialize changes in patch series or not drastically differentiate the
way of using $DVCS for package maintenance.

My question is whether we have a guideline about *where* to document
branch layout for a given package. Regarding Debian,
debian/README.source comes to mind quickly, but its current description
in policy does not make it clear that it is the suitable place where to
document branch layout.

Of the two one: we clarify its description, we describe where else the
branch layout should be documented.

A more general question is whether there is a fixed set of "well known"
branch layouts that can be written down so that we can reference each
layout with a clear name. If this is so, I believe this is the right
place where to attempt defining such a set.

Cheers

PS I've tried a while ago raising this question on the debian-devel
   mailing list, with scarce success (i.e. 0 replies)
   http://lists.debian.org/debian-devel/2008/06/msg00518.html

--

-- 
Stefano Zacchiroli -*- PhD in Computer Science \ PostDoc @ Univ. Paris 7
zack@{upsilon.cc,pps.jussieu.fr,debian.org} -<>- http://upsilon.cc/zack/
(Continue reading)

Permalink | Reply |
headers
Russ Allbery | 15 Jul 22:45
Favicon

Re: [debian] where to document branch layout

Stefano Zacchiroli <zack@...> writes:

> My question is whether we have a guideline about *where* to document
> branch layout for a given package. Regarding Debian,
> debian/README.source comes to mind quickly, but its current description
> in policy does not make it clear that it is the suitable place where to
> document branch layout.

The intention is to use that file for anything that helps explain how to
make changes to a Debian source package.  I think this would qualify.

> A more general question is whether there is a fixed set of "well known"
> branch layouts that can be written down so that we can reference each
> layout with a clear name. If this is so, I believe this is the right
> place where to attempt defining such a set.

FWIW, I've been keeping notes on what I'm personally doing at:

    http://www.eyrie.org/~eagle/notes/debian/git.html

--

-- 
Russ Allbery (rra@...)             <http://www.eyrie.org/~eagle/>
Permalink | Reply |
headers
Stefano Zacchiroli | 16 Jul 00:04
Favicon

Re: [debian] where to document branch layout

On Tue, Jul 15, 2008 at 01:45:16PM -0700, Russ Allbery wrote:
> > branch layout for a given package. Regarding Debian,
> > debian/README.source comes to mind quickly, but its current description
> > in policy does not make it clear that it is the suitable place where to
> > document branch layout.
> The intention is to use that file for anything that helps explain how to
> make changes to a Debian source package.  I think this would qualify.

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.

> FWIW, I've been keeping notes on what I'm personally doing at:
>     http://www.eyrie.org/~eagle/notes/debian/git.html

This is very interesting, thanks a lot for it! What others here do think
of the workflow / branch layout you propose? Are there any other usual
suspect as possible workflows / layouts?

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
(Continue reading)

Permalink | Reply |
headers
Russ Allbery | 16 Jul 00:39
Favicon

Re: [debian] where to document branch layout

Stefano Zacchiroli <zack@...> 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
(Continue reading)

Permalink | Reply |
headers
Stefano Zacchiroli | 16 Jul 09:23
Favicon

Re: [debian] where to document branch layout

On Tue, Jul 15, 2008 at 03:39:27PM -0700, Russ Allbery wrote:
> 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.

Yes, the distinction might have sense, as explained in the current
wording, which states that the target of README.source is who ends up
having in her hands a source package.

But then we are back at the initial problem: where to document branch
layout and other DVCS related information. Even though this is not a
need for the random NMUer, it is a need for someone willing to
contribute "more" to the package, for example to propose a significant
change. In that case, understanding branch layout and publishing a
proper branch is definitely helpful.

Of the two one: either we say README.source is the right place or we
define a new suitable place.

> 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.

That was what I feared ...

> 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
(Continue reading)

Permalink | Reply |
headers
Russ Allbery | 16 Jul 19:27
Favicon

Re: [debian] where to document branch layout

Stefano Zacchiroli <zack@...> writes:

> I see. So basically you are accepting the fact that your .diff.gz get
> "dirty", considering (I guess) that patches are clear enough while
> looking at the git repo.

Yes.  I'm not particularly happy with that, but it turns out that most of
my current packages don't have a large enough delta against upstream for
it to be too overwhelming.  There are packages that aren't in those
category, and for those frankly I'd probably keep using quilt for the time
being, since exposing the individual patch sets in Git seems very
difficult and fairly annoying.

I'm still hoping for better tools.

--

-- 
Russ Allbery (rra@...)             <http://www.eyrie.org/~eagle/>
Permalink | Reply |
headers
Guido Günther | 21 Jul 05:31

Re: [debian] where to document branch layout

On Wed, Jul 16, 2008 at 12:04:38AM +0200, Stefano Zacchiroli wrote:
> On Tue, Jul 15, 2008 at 01:45:16PM -0700, Russ Allbery wrote:
[..snip..] 
> > FWIW, I've been keeping notes on what I'm personally doing at:
> >     http://www.eyrie.org/~eagle/notes/debian/git.html
Very interesting reading!
> 
> This is very interesting, thanks a lot for it! What others here do think
> of the workflow / branch layout you propose? Are there any other usual
> suspect as possible workflows / layouts?
Despite of filtering non dfsg things out onto upstream/ already I
usually import the verbatim upstream sources as is and create a
dfsg-clean branch instead:

git-branch dfsg-clean upstream
rm doc/rfc*

and in $REPO/.git.conf:

[git-buildpacakge]
upstream-branch = dfsg-clean

[git-import-orig]
debian-branch = dfsg-clean

This lets git-buildpackage build the orig.tar.gz form dfsg-clean 
while git-import-orig merges onto dfsg-clean instead of master (so if
you've removed the rfcs once, they'll stay gone forever).  This is has
the minimal advantage that co-maintainers don't have to worry about the
correct import line when importing new upstream versions.
(Continue reading)

Permalink | Reply |

Gmane