Re: Missing package documentation reminder

Hi, Sorry I haven't replied, I've been working like crazy the last days (and will be doing so the next days) and thus I haven't been able to sit down much at a computer and look at emails/newsgroup. This is the latest post I got via email so if more posts have come via the newsgroup then I apologies for that but I don't have access to a nntp client atm ;p On 11/7/06, Gregory Beaver <greg@chiaraquartet.net> wrote:

Helgi Þormar Þorbjörnsson wrote: Actually it is enough, if you'd read the guidelines to PEAR then you'll see that docs aren't required until you are releasing stable versions so I'd say that either guidelines have changed while I wasn't watching or that you haven't read them carefully enough :-) Hi Helgi, I respect the crunch of time, I imagine as a developer you receive far more emails than I do. If I were in your shoes, I would probably use a mail filter, as I've found this is more than effective in moving reminder messages into a folder where I can look at them later.

Well of course I use filters, but it's the principle that I wanted to see corrected ... Having things in PEAR contredict each other isn't very nifty to see for new comers IMHO but well .... Of course, this message comes once a month, and so it is also easy to

just delete it, but I suspect it isn't the *volume* of mail that is bothering you, but just the *principle* of the thing, right?

Hah exactly, should have read this line before writing the line above :) The guidelines have not changed, only stable packages are required to

have documentation. However, the number of undocumented packages is too high (most of mine are undocumented, for instance). It gives PEAR a very bad reputation amongst the masses, as you undoubtedly have encountered. If we can fix this through other means, please let us know your ideas, but what PEAR has been doing for the past 7 years is not working, and will not work.

Well bad rep indeed but I'm still stand pretty strong on the idea that only stable and maintaned packages should get this email ... If a package is old and has been in beta stage forever but is considered stable by the developer then it's the job of QA to catch that and resolve the issue and thus requiring at least minimum docs and at the same time the doc team has get a kick in the ass, just look at the php doc team ;) (beat this has been brough up countless times at our doc list) If a package suffers from no docs then the doc team can whip up the basic docs, one page, linking to all the examples in CVS/SVN (if they do exist), it can be a tad much for a developer to learn the pear docbook stuff, I mean not even I know it ;) Also, although Christian wrote the code, the idea for the reminder email

was mine, feel free to yell at me instead of him :).

Yeah my "anger" wasn't directed at Christian at any rate, the work is good and even needed. By the way, if you don't actually have enough time right now to maintain

the package, this is fully supported in the website, just mark yourself inactive and voila - all the reminder emails go away (right Christian? If not, we need to have a pow-wow). When the time returns, it is simple to reverse that and we of course welcome back prodigal developers as you know :).

Nope marking my self as inactive on the site won't work and even removing my self from the package via the site doesn't either, Christian said he parses the package.xml file where I was for example still added in Cache (just lazyness to update) but think about it ... package xml v1 doesn't offer the inactive .... kinda much to update to v2 just because I don't want to get the mails (I mean on package like Tree where I don't want to remove my self but want to mark my self as inactive) This is why I proposed the pearweb driver approach, so it can be run on the pear machine and use the database straight, there's the info we should go after IMHO.

Ohh I didn't know he got god rights to PEAR (= But all phun aside then from what I can gather in your email then what ... 4 people said okey to this whole email flood ? (if I include Arnaud and Greg) As with many proposals, there was 2-3 weeks of medium traffic on pear-dev about this process, including test displays of the functionality, and feedback from 10 or so developers (I'm estimating here). As far as I remember, the only negative feedback was on mistakes in the processing (packages marked as undocumented that actually were documented), so your complaint is the first. Understandable since you've been busy, of course.

Well okey fine then, I'll take your word for it, maybe the new Pan version isn't doing such a great job showing me new messages when I fire up that sucker.

Maybe I'm being too harsh on this whole thing but I think it the concept needs a little tweaking before being as affective as it can be and still follow the guidelines. Loath me if you like but I think this is pretty important what I was trying to get across here above. Nobody loathes you :) and this is not a stand-off, we don't need to fight. You mentioned having the doc team take care of unmaintained/deprecated documentation. This is not a bad idea, but we need to clearly define the "doc team" in some way. Nobody will step forward otherwise.

Well ... I have no experience there, Sean is the only person I know that has dived into that jungle but he quit because of lack of time or so ... Plus the pear docbook is mess I'm told compared to the php docbook because we use a lot of weird voodoo magic ... I think that's something that makes many people think twice before going into this whole thing. So I suppose some other people will ahve to define what the doc team really is. Christian: what if we took Helgi's suggestion and removed the doc emails

for unmaintained/deprecated packages, and replaced it with a manual page listing the unmaintained/deprecated packages that need documentation? This way, doc folks could erase lines from the page as they fix stuff. As for stable vs. unstable packages, Helgi could we work out a compromise where you can accept the reminder email and we'll fix the unmaintained/deprecated issue? After all, it's not like the docs magically appear for stable releases, the docs need to be written prior to the first stable release, i.e. while the package is still unstable.

Should be fine I think, depends if you mean reminder emails as in I can accept all or none (unstable ones that is, stable ones must always go through, no opt-out) or do you mean per package bases ? But well both should be fine I suppose, even having both options is even better, might be harder to code (well more time consuming) and might be confusing but it's powerful ;P Would this ease your pain Helgi? As I hope is clear, any good idea

(yours included) must influence the process, and I think we can work out the differences you have quite easily in this case.

Well it would make things somewhat more professional IMHO without being too much "in your face" style :-) - Helgi