Ubuntu Documentation / Bzr

[Matthew East]

Hi Robert,

Thanks very much for your email.

On 23/08/07, Robert Collins <robertc at robertcollins.net> wrote:
> Sorry that this isn't in-thread, I'm not on the list so my mail client
> is not going to add the right header.

At least for me gmail has picked it up ok. :) I'm adding back in
Steve, Matthew and Michael though.

> In terms of speed, there are patches for bzr 0.91 that increase network
> performance by a factor of 7, and there is a new disk format in the
> works that is increasing local performance too (by a factor of 2-6 in
> some tests).

Ok, that's good news. Do you know if there is any way to host a
compressed archive of a bzr branch (maybe for those on dialup)? We had
this question on irc yesterday from someone trying to download our
gnome-user-docs branch on dialup and he'd been going for 3 hours
without success.

> In terms of how to structure your branches and trees, bzr gives you the
> ability to merge changes between branches, not between files in a single
> branch.
>
> So any documents you want to merge between should be in separate
> branches of the same overall project.
>
> So I'd be thinking that there is a branch for each release, so you can
> do point releases etc. That seems straightforward to me.
>
> Beyond that, you could have a single project with all the kde/gnome/xfce
> docs in it. Or you could have 3 separate mini-projects, one with kde,
> one with gnome etc. Are there common documents between these?

This is something I suspect we would appreciate some guidance with.
I'll explain our current working structure.

https://docteam.ubuntu.com/repos/

We work on new material in the svn trunk, and branch off for each
release after string freeze. However, within each branch/trunk, all
Ubuntu, Kubuntu, Xubuntu and Edubuntu docs are in the same place. They
share:

 * the "common" and "libs" directories, which supply essential system things.
 * the "generic" directory, which contains some documents used by more
than one of the distributions.
 * other minor things.

However, and this is the messy part, the debian/ directory for
ubuntu-docs is the one you see in trunk, and kubuntu-docs and
edubuntu-docs at least keep their debian directory under a
subdirectory ("kubuntu" and "edubuntu" respectively). Packagers then
have to move that directory up a level and replace the debian
directory used by the ubuntu documents in order to build the
kubuntu-docs and edubuntu-docs packages.

I suspect this messy bit is something which is independent of the
question of whether to move to bzr or not; i.e. if we moved we could
keep the existing structure, and it would just be as confusing as it
is already.

However, if bzr/LP provides an easy way to resolve the issue, then
we'd like to hear more about that.

Possible solutions I can think of might be:

 * host the debian directories in separate branches and the rest of
the material in its existing structure.
 * keep the ubuntu, kubuntu and edubuntu material in separate
branches, with its respective debian directory, and the common
documents in a separate branch.

The second solution sounds to me like it would be confusing for
contributors, and I'm worried that hosting different flavours'
documentation separately would lead to a degree of separation which
would discourage sharing of material.

-- 
Matthew East
http://www.mdke.org
gnupg pub 1024D/0E6B06FF