PEAR2 Coding Standards RFC

Hi all,

I have made the requested changes to the PEAR2 Coding
Standards RFC at
h
ttp://wiki.pear.php.net/index.php/PEAR2_Standards.

 * controversial items split out
 * adjustments based on mailing list conversations

I have moved controversial things to
http://wiki.pear.php.net/index.php/Controversial_Changes


Also, I eliminated allfiles.php.  Instead,
PEAR2/Autoload.php can be
used to set up include_path if necessary, and declare
__autoload() if
necessary, and takes care of all problems

1) beginners need only include
'/full/path/to/PEAR2/Autoload.php'; and
then start using classes
2) if a class/file is not found, an exception is thrown that
contains
include_path information and exactly what went wrong, so
users will be
able to report the same information they do now with
"fatal error:
require_once blah.php not found
(include_path=".:/blah")"
3) advanced users still get the benefit of performance
flexibility.

It should be noted that early assertions by Alan about the
lack of
performance benefit from removing require_once have been
disputed by
Gopal, who has found up to 10% performance improvement in
his work at
Yahoo!.  The performance benefit of removing require_once
for advanced
users can be significant.  Most users, however, will not see
more than
2% improvement.

Please review the docs, find any minor mistakes, browse the
proposal,
and let us know what you think

Greg

-- 
PEAR Development Mailing List (http://pear.php.net/)
To unsubscribe, visit: http://www.php.net/unsub
.php

Looking alot better ;)

The only bit that stuck out was the  "What beta status
means"
- full test suite with X% coverage.. - while this is a
" would be nice 
", I think you may have removed 80% of existing pear
packages by this.. 
- perhaps something more simple like, a minimal of example /
test code 
in docs folder. Test suites prefered...
- API approval by the borg ;) * This is probably more suited
to larger 
commonly used packages.. - the smaller ones should have the
API approved 
before they are voted in  on Pepr (although that has been
missed a 
couple of times)

I tend to agree with the competing packages rule now.. - I
think 
filtering proposals through pepr will result in better
results with 
competing packages... - Although I don't think we are going
to ever 
solve the abandonware issue that some existing packages have
already 
become..

Sometimes I wonder if trying to make a 20 collectives out of
~30 active 
developers is really a feasible vision... as I said before,
I'd like to 
be proved wrong on that one though....



Regards
Alan


Gregory Beaver wrote:
> Hi all,
>
> I have made the requested changes to the PEAR2 Coding
Standards RFC at
> h
ttp://wiki.pear.php.net/index.php/PEAR2_Standards.
>
>  * controversial items split out
>  * adjustments based on mailing list conversations
>
> I have moved controversial things to
> http://wiki.pear.php.net/index.php/Controversial_Changes

>
> Also, I eliminated allfiles.php.  Instead,
PEAR2/Autoload.php can be
> used to set up include_path if necessary, and declare
__autoload() if
> necessary, and takes care of all problems
>
> 1) beginners need only include
'/full/path/to/PEAR2/Autoload.php'; and
> then start using classes
> 2) if a class/file is not found, an exception is thrown
that contains
> include_path information and exactly what went wrong,
so users will be
> able to report the same information they do now with
"fatal error:
> require_once blah.php not found
(include_path=".:/blah")"
> 3) advanced users still get the benefit of performance
flexibility.
>
> It should be noted that early assertions by Alan about
the lack of
> performance benefit from removing require_once have
been disputed by
> Gopal, who has found up to 10% performance improvement
in his work at
> Yahoo!.  The performance benefit of removing
require_once for advanced
> users can be significant.  Most users, however, will
not see more than
> 2% improvement.
>
> Please review the docs, find any minor mistakes, browse
the proposal,
> and let us know what you think
>
> Greg
>
>   

-- 
PEAR Development Mailing List (http://pear.php.net/)
To unsubscribe, visit: http://www.php.net/unsub
.php

Alan Knowles wrote:
> Looking alot better ;)
>
> The only bit that stuck out was the  "What beta
status means" - full
> test suite with X% coverage.. - while this is a "
would be nice ", I
> think you may have removed 80% of existing pear
packages by this.. -
> perhaps something more simple like, a minimal of
example / test code
> in docs folder. Test suites prefered...

As with the rest of the proposal, I'm happy to hear lots of
possible
solutions to the "why the hell isn't PEAR more
documented and tested"
problem, as having 30% documentation and lower test coverage
is
unacceptable.

Currently, we have a new requirement of documentation prior
to the
"stable" label for all packages in PEAR.  Moving
this back to "beta" and
adding tests would be risky, it's true, but I don't think
requiring 1 or
2 examples is a good compromise from requiring full tests. 
Perhaps
others will have some input on this one as well.

> - API approval by the borg ;) * This is probably more
suited to
> larger commonly used packages.. - the smaller ones
should have the
> API approved before they are voted in  on Pepr
(although that has
> been missed a couple of times)
>
> I tend to agree with the competing packages rule now..
- I think
> filtering proposals through pepr will result in better
results with
> competing packages... - Although I don't think we are
going to ever
> solve the abandonware issue that some existing packages
have already
> become..

I am not fond of PEPr personally in that it requires a lot
of up-front
commitment, a fair amount of political wrangling, but almost
nothing
once your package is accepted.  The proposal seeks to
reverse that, so
that projects can be started without much overhead,
improved/modified
while in alpha form without being publicly available on the
website, and
the PEPr stage comes when they are ready to be considered
mature.  The
good thing is that since the code never becomes publicly
available
unless it reaches beta, we can render abandoned alpha
projects to the
trash heap.  Additionally, code that is just not quite ready
can be
revised in svn.pear.php.net instead of on the developer's
home private
server, making it easier to fix the problems
collaboratively.

Much of the abandonware seems to be code that never made it
to the
minimum requirements of docs + tests.  Additionally,
abandoned code that
does have tests and docs is far easier to take over than
code that
doesn't.  By the way, the PEAR2 code would be on
svn.pear.php.net, which
we have full control over thanks to Josh, and this makes
things much
more flexible than they would be through cvs.php.net.

The competing rule of "first package is best"
seems to have made it a
little more difficult to innovate in PEAR if an
implementation (i.e.
Archive_Tar) is questionable or outdated, and I suspect has
led to the
"put every feature possible" bloat.  By having
standard interfaces so
that implementations can be interchangeable (as determined
by
collectives), competing packages are not such a big issue. 
I have faith
that collectives will rule out not-good packages, and will
do it with
more direct knowledge of the code and the problems it solves
than the
entire PEAR-wide repository does now.

Obviously, packages that really are dramatically different
need not have
the same interface or API - and shouldn't.

> Sometimes I wonder if trying to make a 20 collectives
out of ~30
> active developers is really a feasible vision... as I
said before,
> I'd like to be proved wrong on that one though....

We'll see .  Lots of
possible directions.

Greg

-- 
PEAR Development Mailing List (http://pear.php.net/)
To unsubscribe, visit: http://www.php.net/unsub
.php

Hi,

Gregory Beaver wrote:
> I have made the requested changes to the PEAR2 Coding
Standards RFC at
> h
ttp://wiki.pear.php.net/index.php/PEAR2_Standards.
> 
>  * controversial items split out
>  * adjustments based on mailing list conversations
> 
> I have moved controversial things to
> http://wiki.pear.php.net/index.php/Controversial_Changes


Thanks, that looks a lot better now.

> It should be noted that early assertions by Alan about
the lack of
> performance benefit from removing require_once have
been disputed by
> Gopal, who has found up to 10% performance improvement
in his work at
> Yahoo!.  The performance benefit of removing
require_once for advanced
> users can be significant.  Most users, however, will
not see more than
> 2% improvement.

I suggest dropping the "performance" argument, as
the fastest way is of course 
putting everything in one huge file, and we get the obvious
question "why don't 
we distribute our packages this way instead?"

-- 
PEAR Development Mailing List (http://pear.php.net/)
To unsubscribe, visit: http://www.php.net/unsub
.php

Alexey Borzov wrote:

> I suggest dropping the "performance"
argument, as the fastest way is of 
> course putting everything in one huge file, and we get
the obvious 
> question "why don't we distribute our packages
this way instead?"

Just as a clarification:
The fastest way for performance freaks is to put all code
the user 
actually uses into a single file. We still generally provide
generic 
solutions. As such distributing things like MDB2 as a single
file would 
likely not produce the best performance for all users.

As such it would be a nice touch if we some day provide a
code compiler 
class, which would generate such single files for speed
freaks, based on 
their criteria. But its not something that I am keen to see
used by the 
masses.

regards,
Lukas

-- 
PEAR Development Mailing List (http://pear.php.net/)
To unsubscribe, visit: http://www.php.net/unsub
.php

Lukas Kahwe Smith schrieb:
> As such it would be a nice touch if we some day provide
a code compiler
> class, which would generate such single files for speed
freaks, based on
> their criteria. But its not something that I am keen to
see used by the
> masses.

As it seems, PHP will get a "one namespace per
file" implementation.
This would make it impossible to merge code into one file
when
namespaces are used. There was a discussion about merging
into a single
file on PHP-DEV a while ago, and Rasmus said that the
performance
benefit would be neglegible when a cache (read: APC) is
used
(http://www.mail
-archive.com/internalslists.php.net/msg28982.html).

There seems to be endless confusion about this. Without
wanting to put
oil near anything hot, are there any benchmarks comparing
the different
scenarios?

Kind regards,

Stefan

-- 
 >e-novative> - We make IT work for you.

 e-novative GmbH - HR: Amtsgericht München HRB 139407
 Sitz: Wolfratshausen - GF: Dipl. Inform. Stefan Priebsch

 http://www.e-novative.de


-- 
PEAR Development Mailing List (http://pear.php.net/)
To unsubscribe, visit: http://www.php.net/unsub
.php

Stefan Priebsch wrote:
> Lukas Kahwe Smith schrieb:
>   
>> As such it would be a nice touch if we some day
provide a code compiler
>> class, which would generate such single files for
speed freaks, based on
>> their criteria. But its not something that I am
keen to see used by the
>> masses.
>>     
>
> As it seems, PHP will get a "one namespace per
file" implementation.
>   
Not so.

http://news.p
hp.net/php.internals/31860
http://news.p
hp.net/php.internals/31861

Greg
> This would make it impossible to merge code into one
file when
> namespaces are used. There was a discussion about
merging into a single
> file on PHP-DEV a while ago, and Rasmus said that the
performance
> benefit would be neglegible when a cache (read: APC) is
used
> (http://www.mail
-archive.com/internalslists.php.net/msg28982.html).
>
> There seems to be endless confusion about this. Without
wanting to put
> oil near anything hot, are there any benchmarks
comparing the different
> scenarios?
>
> Kind regards,
>
> Stefan
>
>   

-- 
PEAR Development Mailing List (http://pear.php.net/)
To unsubscribe, visit: http://www.php.net/unsub
.php

Alexey Borzov wrote:
> Hi,
>
> Gregory Beaver wrote:
>> I have made the requested changes to the PEAR2
Coding Standards RFC at
>> h
ttp://wiki.pear.php.net/index.php/PEAR2_Standards.
>>
>>  * controversial items split out
>>  * adjustments based on mailing list conversations
>>
>> I have moved controversial things to
>> http://wiki.pear.php.net/index.php/Controversial_Changes

>
> Thanks, that looks a lot better now.
>
>> It should be noted that early assertions by Alan
about the lack of
>> performance benefit from removing require_once have
been disputed by
>> Gopal, who has found up to 10% performance
improvement in his work at
>> Yahoo!.  The performance benefit of removing
require_once for advanced
>> users can be significant.  Most users, however,
will not see more than
>> 2% improvement.
>
> I suggest dropping the "performance"
argument, as the fastest way is
> of course putting everything in one huge file, and we
get the obvious
> question "why don't we distribute our packages
this way instead?"
The point here is also that combining into a single file is
possible
without code modification for more packages if require_once
is
eliminated, but one must remember that multiple files also
means we
preserve line number information, which is much better for
debugging. 
The tradeoff between maintainability and performance is
balanced in this
way.  So yes, performance is still an argument even for
separate files.

Greg

-- 
PEAR Development Mailing List (http://pear.php.net/)
To unsubscribe, visit: http://www.php.net/unsub
.php