Proposal: Create product for each derivative's documentation

[Matthew East]

Ok, this thread has got wildly off-topic, but Dean's email is a good
opportunity to bring it back on-topic.

On Thu, Apr 9, 2009 at 1:49 PM, Dean Sas <dean at deansas.org> wrote:
> I don't think I understand enough to have an opinion, it doesn't sound
> like a terribly big difference either way. It would be nice if the
> proper process had been followed and we should have consistency
> between the various ubuntu flavours.
>
> Perhaps someone could sum up the advantages and disadvantages of each
> approach in a simple list?

Here's my attempt at a dispassionate pro/con analysis. Obviously it's
not totally unbiased, because I do have a view about what are genuine
advantages, and what are not real advantages at all. However, I've
done my best.

I think that in the end, you're right about it not being a huge
difference each way.

Before starting with the pro/con analysis, a brief explanation for
those not familiar with Launchpad about how its package/project
distinction works.

Launchpad distinguishes between distributions (like Ubuntu) and
upstream projects. Distributions have lots of packages. We currently
use both packages (ubuntu-docs, kubuntu-docs, xubuntu-docs,
edubuntu-docs) and a single upstream project (ubuntu-doc). The
upstream project has previously had all our code branches on it, and
it is used because Launchpad doesn't (yet) permit code to be hosted
directly on Ubuntu packages, it requires an upstream project to be
present.

The issue on this thread is whether to make lots of upstream projects
which match the packages, so we'd have one upstream project for each
package. An "umbrella" project would be used to contain each upstream
project, like this: https://launchpad.net/mozilla

Ok, so onto the pro/con analysis. I've used xubuntu-docs for specific
examples, but the same applies to all flavours.

= Benefits of multiple Launchpad projects =

1. Simpler bzr shortcuts. With a single project, to get a branch, you
need to do "bzr branch lp:~ubuntu-core-doc/ubuntu-doc/xubuntu-jaunty"
to get the xubuntu-jaunty branch. With separate projects, you can do
"bzr branch lp:xubuntu-docs/jaunty" (or just lp:xubuntu-docs for the
current development version)

2. Ability to link series to Ubuntu packages. Each project on
Launchpad has the ability to specify "series". In our case, we use
series which match the Ubuntu releases, so "jaunty", "karmic", etc.
Launchpad permits linking packages in Ubuntu to an upstream release
series in the upstream project. Currently, this is only done for
ubuntu-docs because you can't have multiple series in an upstream
project. For an example of the linking in action, see
https://launchpad.net/ubuntu/+source/ubuntu-docs. As far as I'm aware,
we have never actually gained any concrete advantage by this linking,
though. I don't know whether we are missing out on anything.

3. Ability to link the upstream project to Ubuntu translation
templates. Launchpad has the ability to link the translations for an
upstream project to its translations in the Ubuntu package. Cody has
done this here: https://translations.launchpad.net/xubuntu-docs. We
have never used this "feature" in the ubuntu-doc project, and I don't
actually think there are any concrete practical advantages to it,
because the Ubuntu translation teams are accustomed to working
directly on the Ubuntu package translations already, because that is
where they translate for all other Ubuntu packages.

= Cons of Separate Projects =

1. The need to maintain series and other project details separately.
When we add a new series for each release, this currently only needs
to be done once. If we move to separate projects, the act of creating
a new release series will need to be done over each upstream project.
Any changes to the project details will need to be done in each
project rather than just once. Not a huge deal, but some extra
maintenance, and a potential for getting out of sync if people do not
take care of them.

2. Potential for divergence (warning: this is subjective and my
opinion, but others in the group have expressed a similar concern so I
think I'm justified in including it). I think that having separate
projects, even when included in an umbrella project, contains a stigma
that these branches are to be separated and that different teams take
care of them. For example, when Cody created the xubuntu-docs upstream
project, he marked a different team as its "Driver", the xubuntu-docs
team. I think that moving to separate projects entails a risk (and I'm
not putting it higher than a "risk") that the branches will drift
further apart than they already are, and the people working on them
will drift further apart than they already are. I think that it would
be a move in the wrong direction, because the ubuntu-doc project is
part of Ubuntu, and should be working in the Ubuntu distribution area
of Launchpad wherever possible. I think the more "upstream" projects
we create, the further away from that we get.

So that is my best shot at this. As you can see, there aren't huge
differences either way. We could easily try separate upstream
projects, and see how it goes, and evaluate it in 6 months, for
example. We could just stay as we are. In the end, it's not going to
make a huge different to how to work, but we do need to pick one, we
can't carry out with one foot in one camp and one foot in the other.

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