Help with integrating Gnome docs into Ubuntu

[Matthew East]

Hi all,

* Shaun McCance:
> On Sun, 2007-07-15 at 03:31 +1200, Matthew Paul Thomas wrote:
>> On Jul 5, 2007, at 7:30 PM, Matthew East wrote:
>>> ...
>>> The basic problem we are having though is that Ubuntu customises quite 
>>> a lot of Gnome, and as a result the Gnome documentation is wrong, and 
>>> we need to correct it. An example is the layout of the System menu, 
>>> which in Ubuntu does not contain the screenshot/lockscreen buttons, 
>>> but which are part of vanilla Gnome and therefore documented in the 
>>> Gnome user guide.
>>>
>>> The two possible ways of correcting these are:
>>>
>>> 1. Creating patches on the Gnome documentation in the Ubuntu packages 
>>> of gnome-user-docs.
>>> 2. Creating a separate tree with a copy of the Gnome documentation (to
>>> be updated from time to time) and shipping it separately in a new
>>> package, or with the Ubuntu-specific documentation.
>>> ...
>> There is a third way: Use distributed version control.
>>
>> The GDP could have its own branch, Ubuntu could have its own branch, 
>> and any other distributor that used a customized Gnome could have its 
>> own branch. Ubuntu could merge any useful changes from the GDP, while 
>> ignoring those that weren't relevant to Ubuntu. The GDP could merge any 
>> useful changes from Ubuntu, while ignoring those that apply to 
>> Ubuntu-specific customizations. And if two or more distributors made 
>> the same customizations, they could merge corresponding documentation 
>> changes from each other.

This is an interesting idea. I'd very much like to find out how easy it
is to merge/reject different changes from a branch while maintaining a
patch.

> Could distributed version control help alleviate these
> issues?  Possibly.  I'm not a big version control geek,
> so I haven't really played with these other systems.
> But it's unlikely the GDP upstream is going to change
> systems unless Gnome does so.  Although I think I've
> seen people blog about using bzr and git with bridges
> to svn, so maybe you guys can do that on your end.

Ok, let's give this a go. I've arranged an import from svn to bzr
through Launchpad's semi-automatic feature:

https://code.launchpad.net/~vcs-imports/gnome-user-docs/trunk

The next step would be to try to create an Ubuntu-customised branch, and
to try and merge any updates coming into upstream which don't conflict
with such changes on a regular basis. I don't know much about how bzr
works so hopefully mpt will help out with that.

> This is why I generally don't like vendor customizations.
> The cost of maintaining a code patch is generally very
> low compared to the cost of the auxiliary patches, such
> as documentation and translation.

I'm with you: they should be kept to a minimum. Sometimes however, they
are necessary so it makes sense for us all (even Gnome as upstream) to
think about potential ways to overcome the issue.

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

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 252 bytes
Desc: OpenPGP digital signature
URL: <https://lists.ubuntu.com/archives/ubuntu-doc/attachments/20070716/e3882f65/attachment.pgp>