Re: [gentoo-dev] Maintainer's guides?

[Paul de Vrieze]

On Sunday 27 November 2005 18:43, Diego 'Flameeyes' Pettenò wrote:
> On Thursday 24 November 2005 12:31, Diego 'Flameeyes' Pettenò wrote:
> > What I'm waiting for now are comments if someone has ideas where to
> > put guides that does not belong directly to an existant project. And
> > if someone wants to join the effort of documenting maintenance
> > process for his packages, it would be helpful, too.
>
> Trying not to let this idea die, as I still think it might be good in
> the long run, especially if there's a way to get them collected in a
> single place. Right now the main problem is that they are spread across
> projects (at least video/sound projects).
>
> Possible solutions I thought of:
>
> 1) have every herd controlled by a project, so that the maintainers'
> guides can be committed there; it would be difficult to find the
> maintainer's guide for a package this way;
> 2) have a single repository for maintainers' guides that does not
> belong to other projects;
> 3) have a single repository for *every* maintainers' guide.
>
> The problem with 1 and 2 is that the maintainers' guides would be
> difficult to locate in the mess of projects. The problem of 3 is that
> we have already complex maintainers' guides such as xine's and the one
> spyderous wrote for X11 herd, that might be difficult to fit in a
> single organization..
>
I agree with you. Although it is straightforward to provide a reverse 
mapping from packages to herds to projects, that currently doesn't exist.

> To solve 1's and 2's problem, the solution could be adding a
> <maintainerguide> tag to metadata.xml, that carries the URL to the
> maintainer's guide for the package. It would also make simpler, for
> example, the case where a single guide is used for more than one
> package (see always xine's).

In any way I like the idea to add a tag to the metadata.xml files. I would 
however want to do it differently. I'd like to propose a general <doc> 
tag with the usual attributes (version/deprange, language) and as new 
attributes a "src" and a "kind" attribute. For your case it would then 
be:

<doc xml:lang="en_EN" src="/proj/en/audio/xine-maint.xml" 
kind="maintainerguide"/>

This way other gentoo (and other) documentation could be linked to the 
package.

Paul

ps. We might even link to external (upstream) documentation, and have 
packages.gentoo.org provide that info.

-- 
Paul de Vrieze
Gentoo Developer
Mail: pauldv@g.o
Homepage: http://www.devrieze.net