[gentoo-dev] Maintainer's guides?

[gentoo-dev] Maintainer's guides?

[Diego 'Flameeyes' Pettenò]

[-- Attachment #1: Type: text/plain, Size: 1027 bytes --]

As someone probably already know (thru my blog or by looking to my commits), 
I'm being lately working on documenting the process I use to maintain some of 
my packages, in particular xine[1], vlc[2] and alsa[3].

I'm going in the next days to add more and more documentation about this as I 
want to leave enough notes for someone else to step over if I have to go away 
for a medium/long period.

Now the problem is that while xine vlc and alsa belongs to sound and video 
projects, and I'm writing the maintainers' guides there, other packages such 
as rtorrent, bsdtar and netatalk does not belong to a project, so I don't 
know where to stick those maintainers' guides in.

Does anybody have options?

[1] http://www.gentoo.org/proj/en/desktop/video/xine.xml
[2] http://www.gentoo.org/proj/en/desktop/video/vlc.xml
[3] http://www.gentoo.org/proj/en/desktop/sound/alsa.xml
-- 
Diego "Flameeyes" Pettenò - http://dev.gentoo.org/~flameeyes/
Gentoo/ALT lead, Gentoo/FreeBSD, Video, AMD64, Sound, PAM, KDE

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

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

[Diego 'Flameeyes' Pettenò]

[-- Attachment #1: Type: text/plain, Size: 904 bytes --]

On Thursday 24 November 2005 01:01, Diego 'Flameeyes' Pettenò wrote:
> I'm going in the next days to add more and more documentation about this as
> I want to leave enough notes for someone else to step over if I have to go
> away for a medium/long period.
Okay, brix suggested me to explain better what I meant as the phrasing sucked 
(as often from me).

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.

If there's enough volunteers to document the packages, it might be worth 
having a "maintainers' guides" project to save all the guides to..

-- 
Diego "Flameeyes" Pettenò - http://dev.gentoo.org/~flameeyes/
Gentoo/ALT lead, Gentoo/FreeBSD, Video, AMD64, Sound, PAM, KDE

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

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

[Grant Goodyear]

[-- Attachment #1: Type: text/plain, Size: 962 bytes --]

Diego 'Flameeyes' Pettenò wrote: [Thu Nov 24 2005, 05:31:32AM CST]
> 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.

Assuming that they're reasonably well written, why not add them to The
Doc?  Alternatively (and perhaps more usefully), what about permitting a
MaintainerNotes file in any cat/pkg directory where it would be useful?
A plain text file would be easier for people to create and maintain, and
its presence would quickly alert devs to potential quirks with a
possibly unfamiliar package.  Of course, the drawback would be the
additional tree bloat.

-g2boojum-
-- 
Grant Goodyear	
Gentoo Developer
g2boojum@gentoo.org
http://www.gentoo.org/~g2boojum
GPG Fingerprint: D706 9802 1663 DEF5 81B0  9573 A6DC 7152 E0F6 5B76

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

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

[Diego 'Flameeyes' Pettenò]

[-- Attachment #1: Type: text/plain, Size: 1621 bytes --]

On Thursday 24 November 2005 14:51, Grant Goodyear wrote:
> Assuming that they're reasonably well written, why not add them to The
> Doc?
For the same reason the doc born outside GDP: quick changes, for once. for 
example the xine mantainer's guide yesterday was changed "on the spot" when 
the TEXTRELs problem was found, both its and vlc's guides were changed as 
soon as I moved the patchsets in gentoo CVS.
The point is to have maintainers update their notes as they do them. If a new 
release come up, I can quickly update the notes about it.

> Alternatively (and perhaps more usefully), what about permitting a 
> MaintainerNotes file in any cat/pkg directory where it would be useful?
That would be quite every package, because there's no package "without notes". 
Also the simplest packages might have something that needs to be checked.
And adding one more file to the tree, of considerable size for some cases 
(look at xine's guide, it's quite long) would be really bad.
And I still think that something more elaborated than txt can help in writing 
notes about that.. I know that many people does not like GuideXML, but it's 
flexible enough for most of the needs of a packager's notes.
Referring again to the xine's guide, you can find that all the useflags stated 
are in bold.. if someone wants to find out why a given useflag is threated in 
certain way, it's simple to spot it, it's not so simple when you have to do 
it with a plain text file.

-- 
Diego "Flameeyes" Pettenò - http://dev.gentoo.org/~flameeyes/
Gentoo/ALT lead, Gentoo/FreeBSD, Video, AMD64, Sound, PAM, KDE

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

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

[Ciaran McCreesh]

[-- Attachment #1: Type: text/plain, Size: 839 bytes --]

On Thu, 24 Nov 2005 15:08:19 +0100 "Diego 'Flameeyes' Pettenò"
<flameeyes@gentoo.org> wrote:
| On Thursday 24 November 2005 14:51, Grant Goodyear wrote:
| > Assuming that they're reasonably well written, why not add them to
| > The Doc?
|
| For the same reason the doc born outside GDP: quick changes, for
| once.

If I ever get around to regaining enough faith in humanity to do the
"Gentoo Developer Documentation" proposal, quick changes for package
specific sections will be one of the features. Of course, the problem
with that is that some our package maintainers couldn't stick together
a coherent English sentence even if they were paid to do so...

-- 
Ciaran McCreesh : Gentoo Developer (Supreme Lord Gerbil Wrangler)
Mail            : ciaranm at gentoo.org
Web             : http://dev.gentoo.org/~ciaranm


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 189 bytes --]

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

[Diego 'Flameeyes' Pettenò]

[-- Attachment #1: Type: text/plain, Size: 550 bytes --]

On Thursday 24 November 2005 20:50, Ciaran McCreesh wrote:
> Of course, the problem
> with that is that some our package maintainers couldn't stick together
> a coherent English sentence even if they were paid to do so...
That's why I was thinking of a complete project with some doc guys assigned to 
grammar revision.

Not everybody is a native English speaker, and it's stupid blaming people for 
that.

-- 
Diego "Flameeyes" Pettenò - http://dev.gentoo.org/~flameeyes/
Gentoo/ALT lead, Gentoo/FreeBSD, Video, AMD64, Sound, PAM, KDE

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

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

[Ciaran McCreesh]

[-- Attachment #1: Type: text/plain, Size: 1038 bytes --]

On Thu, 24 Nov 2005 20:58:46 +0100 "Diego 'Flameeyes' Pettenò"
<flameeyes@gentoo.org> wrote:
| On Thursday 24 November 2005 20:50, Ciaran McCreesh wrote:
| > Of course, the problem
| > with that is that some our package maintainers couldn't stick
| > together a coherent English sentence even if they were paid to do
| > so...
|
| That's why I was thinking of a complete project with some doc guys
| assigned to grammar revision.

*shrug* I'm not sure that the existing docs team is the best way of
handling developer documentation. It's probably better off with a
separate team, with some people belonging to both as necessary.
 
| Not everybody is a native English speaker, and it's stupid blaming
| people for that.

There doesn't seem to be any strong correlation between being a native
English speaker and being able to write correct English...

-- 
Ciaran McCreesh : Gentoo Developer (Supreme Lord Gerbil Wrangler)
Mail            : ciaranm at gentoo.org
Web             : http://dev.gentoo.org/~ciaranm


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 189 bytes --]

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

[Diego 'Flameeyes' Pettenò]

[-- Attachment #1: Type: text/plain, Size: 913 bytes --]

On Thursday 24 November 2005 21:25, Ciaran McCreesh wrote:
> *shrug* I'm not sure that the existing docs team is the best way of
> handling developer documentation.
If it's just matter of fixing the English in it, I don't think there's much 
technical matter they would be required to think about.
I'm not saying they should write *more* of it, it's just a way to clean up the 
form of something written by the techies.

> | Not everybody is a native English speaker, and it's stupid blaming
> | people for that.
> There doesn't seem to be any strong correlation between being a native
> English speaker and being able to write correct English...
You might not be able to see it because you're one, so don't even try to find 
lame reasons. It's not _easy_ at all.

-- 
Diego "Flameeyes" Pettenò - http://dev.gentoo.org/~flameeyes/
Gentoo/ALT lead, Gentoo/FreeBSD, Video, AMD64, Sound, PAM, KDE

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

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

[Grobian]

Diego 'Flameeyes' Pettenò wrote:
> On Thursday 24 November 2005 21:25, Ciaran McCreesh wrote:
>> *shrug* I'm not sure that the existing docs team is the best way of
>> handling developer documentation.
> If it's just matter of fixing the English in it, I don't think there's much 
> technical matter they would be required to think about.
> I'm not saying they should write *more* of it, it's just a way to clean up the 
> form of something written by the techies.

Beware that this can get tricky; sometimes it's very easy to change the 
meaning of a sentence by 'correcting' it.  Hence a feedback loop sounds 
like a necessity.

>> | Not everybody is a native English speaker, and it's stupid blaming
>> | people for that.
>> There doesn't seem to be any strong correlation between being a native
>> English speaker and being able to write correct English...
> You might not be able to see it because you're one, so don't even try to find 
> lame reasons. It's not _easy_ at all.

If you look at the quote below, I think that it is not easy for anyone. 
  Hence, you need designated people for such job as corrector and get a 
certain style for your text.

> | On Thursday 24 November 2005 20:50, Ciaran McCreesh wrote:
> | > Of course, the problem
> | > with that is that some our package maintainers couldn't stick
> | > together a coherent English sentence even if they were paid to do
> | > so...

-- 
Fabian Groffen
Gentoo for Mac OS X Project -- Interim Lead
-- 
gentoo-dev@gentoo.org mailing list

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

[Diego 'Flameeyes' Pettenò]

[-- Attachment #1: Type: text/plain, Size: 1709 bytes --]

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..

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).

-- 
Diego "Flameeyes" Pettenò - http://dev.gentoo.org/~flameeyes/
Gentoo/ALT lead, Gentoo/FreeBSD, Video, AMD64, Sound, PAM, KDE

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

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

[Donnie Berkholz]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Diego 'Flameeyes' Pettenò wrote:
| Possible solutions I thought of:
|
| 1) have every herd controlled by a project

This should be the goal already, and all herds should be looking to
either join or create a project, in conjunction with other herds.

Thanks,
Donnie
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.2 (GNU/Linux)

iD8DBQFDigitXVaO67S1rtsRAj3MAJ0e94IaRqF3QAlQDBeKU/AJtw1J9ACfZHRf
6PiASl9wYGQ59dQ8HNXTG6I=
=80iT
-----END PGP SIGNATURE-----
-- 
gentoo-dev@gentoo.org mailing list

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

[Diego 'Flameeyes' Pettenò]

[-- Attachment #1: Type: text/plain, Size: 532 bytes --]

On Sunday 27 November 2005 20:27, Donnie Berkholz wrote:
> This should be the goal already, and all herds should be looking to
> either join or create a project, in conjunction with other herds.
Okay that probably goes fine for most of the cases, there are still non-herded 
ebuilds but that's a side problem.
Anyway if the organization is non-trivial, the metadata thing is really 
needed.

-- 
Diego "Flameeyes" Pettenò - http://dev.gentoo.org/~flameeyes/
Gentoo/ALT lead, Gentoo/FreeBSD, Video, AMD64, Sound, PAM, KDE

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

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

[Paul de Vrieze]

[-- Attachment #1: Type: text/plain, Size: 2539 bytes --]

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@gentoo.org
Homepage: http://www.devrieze.net

[-- Attachment #2: Type: application/pgp-signature, Size: 198 bytes --]

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

[Diego 'Flameeyes' Pettenò]

[-- Attachment #1: Type: text/plain, Size: 840 bytes --]

On Monday 28 November 2005 11:39, Paul de Vrieze wrote:
> 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.
I like this idea, as it would also allow to specify user documentation that 
can be found on GDP, allowing users to find out the link to alsa guide 
directly from an alsa-* package's metadata.
Maybe instead of a kind attribute we can have a "title" attribute, it would be 
anyway simple to recognize maintainers' guides, as they would be all 
title="Maintainer's Guide".

-- 
Diego "Flameeyes" Pettenò - http://dev.gentoo.org/~flameeyes/
Gentoo/ALT lead, Gentoo/FreeBSD, Video, AMD64, Sound, PAM, KDE

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

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

[Paul de Vrieze]

[-- Attachment #1: Type: text/plain, Size: 1162 bytes --]

On Monday 28 November 2005 11:55, Diego 'Flameeyes' Pettenò wrote:
> On Monday 28 November 2005 11:39, Paul de Vrieze wrote:
> > 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.
>
> I like this idea, as it would also allow to specify user documentation
> that can be found on GDP, allowing users to find out the link to alsa
> guide directly from an alsa-* package's metadata.
> Maybe instead of a kind attribute we can have a "title" attribute, it
> would be anyway simple to recognize maintainers' guides, as they would
> be all title="Maintainer's Guide".

Perhaps we should do both, as "title" attributes are not easy for machines 
to understand, as they are freeform. The kind attribute would not be and 
only allow certain values such as: "maintainer", "user", 
"administration", "troubleshooting", "misc"

Paul

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

[-- Attachment #2: Type: application/pgp-signature, Size: 198 bytes --]

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

[Diego 'Flameeyes' Pettenò]

[-- Attachment #1: Type: text/plain, Size: 537 bytes --]

On Monday 28 November 2005 12:20, Paul de Vrieze wrote:
> Perhaps we should do both, as "title" attributes are not easy for machines
> to understand, as they are freeform. The kind attribute would not be and
> only allow certain values such as: "maintainer", "user",
> "administration", "troubleshooting", "misc"
Sort of the way a dev in a project has role and description, then.
Good for me :)

-- 
Diego "Flameeyes" Pettenò - http://dev.gentoo.org/~flameeyes/
Gentoo/ALT lead, Gentoo/FreeBSD, Video, AMD64, Sound, PAM, KDE

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

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

[Jan Kundrát]

[-- Attachment #1: Type: text/plain, Size: 417 bytes --]

On Monday 28 of November 2005 11:55 Diego 'Flameeyes' Pettenò wrote:
> I like this idea, as it would also allow to specify user documentation that
> can be found on GDP, allowing users to find out the link to alsa guide
> directly from an alsa-* package's metadata.

What about setting the HOMEPAGE of alsa-something to point to our ALSA-guide?

Cheers,
-jkt

-- 
cd /local/pub && more beer > /dev/mouth

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

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

[Diego 'Flameeyes' Pettenò]

[-- Attachment #1: Type: text/plain, Size: 467 bytes --]

On Monday 28 November 2005 16:47, Jan Kundrát wrote:
> What about setting the HOMEPAGE of alsa-something to point to our
> ALSA-guide?
Because that's not the homepage?
I go often on pgo to see the homepage of something, and it's usually to get 
*upstream* homepage, not Gentoo's guides.
It's misleading changing that, imho.

-- 
Diego "Flameeyes" Pettenò - http://dev.gentoo.org/~flameeyes/
Gentoo/ALT lead, Gentoo/FreeBSD, Video, AMD64, Sound, PAM, KDE

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

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

[Curtis Napier]

Diego 'Flameeyes' Pettenò wrote:
> On Monday 28 November 2005 16:47, Jan Kundrát wrote:
> 
>>What about setting the HOMEPAGE of alsa-something to point to our
>>ALSA-guide?
> 
> Because that's not the homepage?
> I go often on pgo to see the homepage of something, and it's usually to get 
> *upstream* homepage, not Gentoo's guides.
> It's misleading changing that, imho.
> 

I agree with this. I often don't feel like wading through 5 pages of bad 
results on google to find an obscure packages homepage. I look in the 
ebuild for this information all the time. A seperate tag like <doc>, as 
someone mentioned earlier, would also be a huge help but would still 
give you the homepage info as well.
-- 
gentoo-dev@gentoo.org mailing list

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

[Jan Kundrát]

[-- Attachment #1: Type: text/plain, Size: 626 bytes --]

On Monday 28 of November 2005 21:01 Curtis Napier wrote:
> I agree with this. I often don't feel like wading through 5 pages of bad
> results on google to find an obscure packages homepage. I look in the
> ebuild for this information all the time. A seperate tag like <doc>, as
> someone mentioned earlier, would also be a huge help but would still
> give you the homepage info as well.

Well, I was thinking about guides which usually link homepage of the 
respective package in the first sentence, but Diego is right, our guides are 
not homepages.

Cheers,
-jkt

-- 
cd /local/pub && more beer > /dev/mouth

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

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

[Diego 'Flameeyes' Pettenò]

[-- Attachment #1: Type: text/plain, Size: 485 bytes --]

On Monday 28 November 2005 21:01, Curtis Napier wrote:
> A seperate tag like <doc>, as
> someone mentioned earlier, would also be a huge help but would still
> give you the homepage info as well.
Seems like we are all ok for the <doc> tag in metadata then... should this 
require a GLEP or it's a simple change? Who can take care of that? Paul?

-- 
Diego "Flameeyes" Pettenò - http://dev.gentoo.org/~flameeyes/
Gentoo/ALT lead, Gentoo/FreeBSD, Video, AMD64, Sound, PAM, KDE

[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

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

[pclouds]

On 11/30/05, Diego 'Flameeyes' Pettenò <flameeyes@gentoo.org> wrote:
> On Monday 28 November 2005 21:01, Curtis Napier wrote:
> > A seperate tag like <doc>, as
> > someone mentioned earlier, would also be a huge help but would still
> > give you the homepage info as well.
> Seems like we are all ok for the <doc> tag in metadata then... should this
> require a GLEP or it's a simple change? Who can take care of that? Paul?
When will this tag be added to dtd?
--
Bi Cờ Lao

-- 
gentoo-dev@gentoo.org mailing list