Re: AW: [PEAR-DEV] Documentation

On Sat, 26 Apr 2003, Daniel Khan wrote: > > http://pear.php.net/~mj/004-documentation.txt might be of > > interest for > > you. > > In this case we will need an easy reporting system for end users. > "No propper or deprecated documentation? click here" > Otherwise someone will have to watch over every packages docs. Yup. Someone will. Be it users or someone within the PEAR project who is willing to stand guard over the gates. Call them the release master. They are the final arbiter for any package which wants to go onto the download site. It'll probably only be necessary for new[1] packages which enter the archive - once a version has gone in with decent docs, updating them isn't as much of a hassle and can proceed apace. It is the overall "holy crap this is a big job" of producing initial documentation from someone else's code which gets people down. The release master can have other tasks as well, such as making sure someone isn't trying to sneak in other people's copyrighted (and otherwise unlicenced) code. Is everyone who has a closeish stake in the PEAR project quite sure that there isn't any code in any package which might have a "Copyright (C) J. Random Hacker. All Rights Reserved" in it? If you're trusting the package maintainers, someone, somewhere is going to fluff it one day. Maybe not in a big hurry, since PEAR isn't that big yet, but when companies start using PHP extensively (moreso than they already are) and PHP code starts becoming universal, people are going to start making unwarranted assumptions about cother people's code. Hell, for that matter, are you sure that there isn't some code in PEAR which is GPLd... The initial package approval process, getting a CVS account, or whatever, doesn't need a complete set of docs, release master approval, or any of this extra stuff. That would be ridiculous. But by the time a package wants to enter the PEAR download area, package maintainers *must* be aware that their packages have to meet certain criteria before they'll be accepted. The release master is a double-check against over-hasty developers. It really is a necessity if PEAR wants to obtain (I won't say keep because I don't think they have it at the moment) the reputation of a high-quality, commercially usable code repository, where it is worth J Random Developer's time to check out PEAR before he tries to roll his own. > Not every proposed package is ready for release. So the documentation > may be missing, ... etc Indeed. In that case, hack on it in CVS, keep it hidden from the wider world. But when it hits the package archive, it *is* (supposedly) ready for release, and hence it *should* have complete, readable documentation. > I simply think that this idea will have an impact on the whole approval > process > and to make it real will be much work but I agree that it's the only way to > go. The "package approval" process doesn't need to change so much, but the institution of an archive master who doesn't let anything into the package archive which is total crap would be a change for PEAR, but it wouldn't be a totally new concept. If anyone wants to go with "but, but, we're all volunteers! Who's going to do all this work?" I will hereby step forward and volunteer myself as the archive master. If PEAR wants to maintain quality and avoid possible legal headaches, arbiters of taste will be required somewhere. -- ----------------------------------------------------------------------- #include <disclaimer.h> Matthew Palmer, Geek In Residence http://ieee.uow.edu.au/~mjp16