Splitting ubuntu-docs into multiple projects / helping downstreams

[Matthew East]

On Thu, Jan 21, 2010 at 3:42 PM, Kyle Nitzsche
<kyle.nitzsche at canonical.com> wrote:
> Ubuntu-docs should be split into multiple packages & branches to:

Again this is a separate discussion to the thread that you've raised
it on... I have been waiting to respond properly to the last time that
you raised it as I promised to do but I suppose that this is as good a
time as any. I'm changing the subject line.

I'm totally opposed to the idea of splitting ubuntu-docs into a
different project and different source package for each document that
we produce. I don't think there are any real advantages to doing so,
and I see the disadvantages as potentially nightmarish. So I'm
splitting this email into "for" and "against".

= FOR =

> * facilitate customization of the help content for ubuntu variants (for
> example, some don't use Network Manager)

The main justification that you've used for the proposal is to
facilitate customisation of the help content for downstream users. It
may be that I need to understand better what downstream users are
doing and see some examples, but let's say for the sake of argument
that a downstream user wants to customise two of our documents, and
leave the rest as they are. If we're shipping a single package,
downstream will need to fork that package and introduce its
modifications. I maintain that using the power of version control,
that is actually not that difficult to do: we do it for
gnome-user-docs for example, which is our own upstream.

I don't at the moment understand why it would be any easier in this
hypothetical situation for the downstream user if we are shipping each
document in a separate package. Instead of forking one package, now it
needs to fork two of them. And the effort remains the same: i.e.
version control can be used to track the changes made to our branches.

Mallard will obviously make things quite a lot easier, because
plugging new material in will be easy, and removing or customising
material should also be pretty easy because files will generally be
shorter. But I don't see it as impossible even with our current tools,
and crucially I don't see any appreciable difference in doing it for
one large package, or several packages.

Actually, I see it as more work to do it for several packages. Our
upstreams don't do this. But if they did, for example, if
gnome-user-docs came as separate packages each with different
documents in, it would be much more work for us to keep track of those
and to branch them all.

It may be that I'm missing something so I'm definitely happy to hear
your thoughts on that.

However, even if I am missing something and there is some reason why
such a split would make life hugely better for our downstreams, I'd
still need some serious convincing before I can go along with it
because of what I see as the possible disadvantages of such a split.

Just to deal with the other justifications you've mentioned:

> * facilitate prototyping and development of new great stuff (like mallard
> and l10n of images)

I don't think that is facilitated at all by splitting ubuntu-docs into
separate branches. bzr makes this incredibly easy already:

"bzr branch ubuntu-docs ubuntu-docs-mallard-testing"

Separate branches doesn't make any different to that.

> * to make the size of the branches smaller

Ok, that's a possible reason, yeah. But there are plenty of large
branches around and one shouldn't split just for this reason: it's
still got to be the right thing to do.

= AGAINST =

Counted conservatively, we have 19 different documents currently in
ubuntu-docs. Maintaining separate branches or even separate projects
for each document would increase the amount of maintenance required to
keep Launchpad up to date for each new version of Ubuntu 19 times
(including branching for each release, creating a new release series,
associating the branch etc). Our contributors would have to look in 19
different places to get the source for our documentation. We would
have to issue 19 different commands to get the branches. Committing
changes to more than one document would need to be done separately.
Translations would need to be imported 19 different times (assuming
that we continue to use Launchpad packages for storing our
translations).

A solution would also need to be found for the fact that our documents
rely on common files in libs/, debian/, scripts/ and so on. Either
those folders would need to be reproduced in each branch, in which
case any change to them would need to be synched 19 times, or they
would need to be stored in a separate branch, in which case in order
to view any document, our contributors would need to download that
separate branch into the exact location that makes the document work.

Regardless of which direction I look at this from, I can't see
anything other than a logistical nightmare which would make our lives
more difficult and the lives of our potential contributors more
difficult. There may be things that can be done to reduce some of the
complexity and maintenance that this would cause, but I don't think it
can all be avoided, and at the absolute minimum it would involve
creating more complex tools that might be within the grasp of Ubuntu
developers but are not necessarily within the grasp of contributors to
this team. For this team I feel that keeping things simple is
important.

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