Re: PEAR2 Standards

Jon Parise wrote: > On Mon, Dec 24, 2007 at 05:46:23PM +0100, Arnaud Limbourg wrote: > >> The PEAR Group would like to announce the PEAR2 Standards. We want to >> point out the document is not final. Everybody is encouraged to take a >> look and give feedback. You can refer to the document as "version 1" of >> the standards. > > ... > >> You can find the document at the following url: >> >> http://pear.php.net/manual/en/pear2cs.php > > 1. The "Introduction" section isn't really an introduction. The > first paragraph is sort of an introduction, but the rest of the > section simply extols the virtues of __autoload(). Revisions are welcome > 2. I'm not a fan of the 'PEAR2' namespace. Let's just use > 'PEAR'. > Namespaces don't currently exist for all intents and purposes so > there shouldn't be any conflicts with existing code. It conflicts with all packages with "PEAR_" in the name (PEAR Installer, PEAR_RemoteInstall, PEAR_PackageFileManager, PEAR_Info) and this is not an option. > Has the requirement for this name leaked out of the necessity to > use __autoload()? If so, I would consider that unfortunate. no > 3. Please include more detail on the prohibition of 'include' and > friends. The current document states that users will be expected > to load files via __autoload(), etc. Can the package use > 'include' internally? I don't understand what "import with a No, the package cannot use include internally. That's what this prohibition means. > comment" means. "import with a comment describing the class's location" is a mistaken non-deletion that slipped in from the original draft. This entire sentence should be deleted. It referred to this: <?php // from PEAR/External/ClassName.php import PEAR2::External::ClassName; ?> Which is obsolete for many reasons including the fact that "import" has been replaced by "use". > 4. The required directory structure includes "tests" and "examples" > (plural) but "doc" singular. I would prefer "docs" for > consistency. > > 5. Does PEAR2 have a "tests" role? It appears to be just "test" in > PEAR(1). This will require a new vote by the PEAR Group, but I don't see a problem with the revision personally. The best approach is to send a message to pear-group@php.net and propose the change formally so it can be voted upon. > 6. If package.xml replacement tasks shouldn't be used to retrieve > path locations for 'php', 'data', or 'www' files, I would > suggest > making it impossible to do so instead of adding a prohibition in > the coding standards document. This would make it impossible to use Pyrus to install existing PEAR packages, which is not a goal of the standards. > 7. Please explain how I should go about porting existing PEAR > packages to PEAR2. For example, can I still use PEAR_Error, or > must everything now use PEAR2::Exception? The standards are quite clear on this - PEAR_Error is dead. Existing PEAR packages will need to be extensively re-worked. Here is how it would happen: 1) announce your intentions on pear-dev 2) set up the package in svn.pear.php.net/PEAR/sandbox/<packagename> 3) change files to use namespace declarations 4) use PEAR2_Exception (classname will be PEAR2::Exception) for error handling 5) when you feel ready for beta status, propose the code for review. At this time, a final name will be decided, unlike PEAR, where the name is decided prior to acceptance > 8. I would suggest producing a single "PEAR2 Coding Standards" > document instead of just providing addenda to the existing PEAR(1) > document. The current format is going to be confusing for both > new and existing package authors who haven't been following the > on-going evolution of the standards. Sounds good - and is a huge project. My instinct is that this is best accomplished when the standards have settled a bit, perhaps a month from now or so? Greg