Re: PEAR2 package naming standards (namespace usage)

I would like to start by saying there may be a deficiency in the RFC on explaining exactly what the naming means in terms of file system layout and svn layout since there are no examples. I would appreciate feedback on how we can make all parts of the RFC clearer. I'll start with some examples to make sure we are all on the same page. classname: pear2::foobar::Foo_Bar file layout: pear2/foobar/Foo/Bar.php svn: http://svn.pear.php.net/PEAR2/foobar/trunk/src/foobar/Foo/Bar.php classname: pear2::foo_bar::Foo_Bar file layout: pear2/foo_bar/Foo/Bar.php svn: http://svn.pear.php.net/PEAR2/foo_bar/trunk/src/foo_bar/Foo/Bar.php classname: pear2:foobar::bar::Bar.php file layout: pear2/foobar/bar/Bar.php svn: http://svn.pear.php.net/PEAR2/foobar/trunk/src/foobar/bar/Bar.php Sub-packages != Sub-namespaces Sub-packages are treated like there own top level projects from a namespace perspective My response to each item is below: Baptiste Autin wrote:

First, a preliminary question: what's about http://wiki.pear.php.net/index.php/PEAR2_Standards ? Both RFCs seem to be contradictory. For example, take that (wise) rule taken from Arnaud and Greg's proposition: # All public classes must be in their own file with underscores (_) or namespace separators (::) replaced by directory separator, so that PEAR2_PackageName_Base class or PEAR2::PackageName::Base class is always located in PEAR2/PackageName/Base.php

The PEAR2_Standards RFC will be updated to point to this RFC for naming, the PEAR2_Standards rfc was always meant to be updated hence the expiration date.

And now let's take Travis' proposition: # All underscores (_) in the package name (i.e., everything that's lowercase) will not be translated as anything other than underscores # Underscores within the <ClassName> portion will be treated like PEAR1 to allow for sub-directories without specifying a sub-namespace ?? Now, my comments: 1. Travis'RFC focuses on MDB2, and tries to solve a problem raised by that particular package. Other PEAR packages, even those defining subpackages, may not necessarily meet that problem. The RFC uses MDB2 but we talked about many packages when creating it. Its goal is too increase flexbility and I think it does this by allowing for PEAR1 style class naming or the heavy use of sub-namespaces at the developers discretion.

The problem is (if I understood it correctly) that we want the MDB2 subpackages (the "drivers") to have their own SVN repositories, because we don't want the user to have to download 1 Mo of drivers code, if he only needs the MySQL driver.

The problem is that the PEAR1 setup overlaps files into the same directory. You can can't use an svn external for an HTTP_Request and a HTTP_Header package since they both have a file in the HTTP dir. This RFC means all code for a package is in one base dir and there is no overlap. This does mean that any subpackage is treated like top level package from a namespace/svn level, but that doesn't come into play unless you want to release a subpackage. You can use a sub-namespace or a PEAR1 style dir == _ to organize your code.

But look at large OO applications: their namespaces can contain two, three, four depth levels, with a dozen of subpackages at each level, containing plenty of classes each, and there is only ONE global SVN repo for the whole code, one SVN repo for the whole project. There is some good sense to stick to one versioning repository for a project, especially when it is Subversion. All of PEAR2 in one svn repo (http://svn.pear.php.net/PEAR2), we are

talking about paths within that repo, though really with SVN there isn't a large difference to the end user. The one repo is used to make moving code and its history easier.

Does Michel Gauthier really needs 3 SVN repos, one for his driver Crypt_GPG_Driver_Php, one for his driver Crypt_GPG_Driver_GnuPG, and one for the rest of the code??? This is absurd.

Maybe i've missed something in the 10 times I read this but this RFC doesn't state that. What is does say is: "Each package owns all namespaces within it's package namespace. |pear2::foobar| can define any additional sub-namespaces it wishes to and each sub-namespace will follow the same directory naming schema. " So if you want to use subpackages you will need multiple top-level namespaces If you don't want to use subpackges you can do whatever you want with sub-namespaces.

Have a look at large open-source Java projects (Java is not PHP, nor PEAR - ok! - but it is interesting anyway, because there is a long experience with namespacing in Java, and a long experience with big projects handling as well). Sometimes, you will find one SVN channel for 90% of a project, while the remaining 10% are tracked into 1 or 2 separate SVN repos. This happens when you want to isolate a component that is marginal, or that is stand-alone, or developed by a different team, etc. But this is not that frequent, AFAIK. We did look at open-source java projects, i think I addressed this a couple paragraphs above.

I repeat, MDB2 is a particular case, and it would be dangerous to focus on that package - at the risk of setting up a crooked naming standard. (There is a solution for the MDB2 problem BTW: making its drivers become full PEAR packages, like Structures_DataGrid did with its datasources, which are independant packages, or like they did in Perl, with their abstract layer package DBI. Then the MDB2 drivers would get their own SVN repos. This would mean refactoring MDB2, but it WILL be necessary to change MDB2 anyway) MDB2 wasn't a major driver behind this, its just a common example of subpackages, and in fact this rfc does suggest treating sub-packages much like normal packages from a namespace perspective.

2. In short, Travis, you're saying to us: "Ok, do what you want with your #^§$%*! namespaces, I don't care, but your classes must be named according to the PEAR1 style, with underscores, and the directory structure must conform to the former PEAR1 structure." Not sure we are taking benefit of the namespaces... don't you think? IMO, Arnaud and Greg's initial RFC was enough. Baptiste In my opinion Arnaud and Greg's initial RFC wasn't enough. It largely kept the PEAR1 pattern just replacing _ with ::. I hope with futher clarification it will be clear to everyone that this RFC gives the developer much more flexibility in code organization then the PEAR1 pattern did, while also make it clearer what is the namespace and what is the Class

thanks -joshua eichorn