Re: [gentoo-dev] Maintainer's guides?
On 11/30/05, Diego 'Flameeyes' Pettenò <[EMAIL PROTECTED]> wrote: > On Monday 28 November 2005 21:01, Curtis Napier wrote: > > A seperate tag like , 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 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
Re: [gentoo-dev] Maintainer's guides?
On Monday 28 November 2005 21:01, Curtis Napier wrote: > A seperate tag like , 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 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 pgpKKndDbxD2o.pgp Description: PGP signature
Re: [gentoo-dev] Maintainer's guides?
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 , 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 pgpGeS5jtHA5p.pgp Description: PGP signature
Re: [gentoo-dev] Maintainer's guides?
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 , 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?
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 pgpgWZOKjIFM3.pgp Description: PGP signature
Re: [gentoo-dev] Maintainer's guides?
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 pgp1TFQu6qee2.pgp Description: PGP signature
Re: [gentoo-dev] Maintainer's guides?
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 pgpzmkf9GAzQS.pgp Description: PGP signature
Re: [gentoo-dev] Maintainer's guides?
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 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: [EMAIL PROTECTED] Homepage: http://www.devrieze.net pgpZvmcTUR2df.pgp Description: PGP signature
Re: [gentoo-dev] Maintainer's guides?
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 > 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 pgpLWt874MJVA.pgp Description: PGP signature
Re: [gentoo-dev] Maintainer's guides?
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 > 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 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: 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: [EMAIL PROTECTED] Homepage: http://www.devrieze.net pgpTkeXdPGHSZ.pgp Description: PGP signature
Re: [gentoo-dev] Maintainer's guides?
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 pgpgq6BBJB6tA.pgp Description: PGP signature
Re: [gentoo-dev] Maintainer's guides?
-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?
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 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 pgp9xae7VUadb.pgp Description: PGP signature
Re: [gentoo-dev] Maintainer's guides?
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?
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 pgplP3JJ0cdrz.pgp Description: PGP signature
Re: [gentoo-dev] Maintainer's guides?
On Thu, 24 Nov 2005 20:58:46 +0100 "Diego 'Flameeyes' Pettenò" <[EMAIL PROTECTED]> 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 signature.asc Description: PGP signature
Re: [gentoo-dev] Maintainer's guides?
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 pgpcalDDlCFKk.pgp Description: PGP signature
Re: [gentoo-dev] Maintainer's guides?
On Thu, 24 Nov 2005 15:08:19 +0100 "Diego 'Flameeyes' Pettenò" <[EMAIL PROTECTED]> 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 signature.asc Description: PGP signature
Re: [gentoo-dev] Maintainer's guides?
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 pgpKOVnNJcie4.pgp Description: PGP signature
Re: [gentoo-dev] Maintainer's guides?
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 [EMAIL PROTECTED] http://www.gentoo.org/~g2boojum GPG Fingerprint: D706 9802 1663 DEF5 81B0 9573 A6DC 7152 E0F6 5B76 pgpdPwMPOn195.pgp Description: PGP signature
Re: [gentoo-dev] Maintainer's guides?
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 pgpVy1xnrDFC5.pgp Description: PGP signature
