Re: [PHP-DEV] [RFC] [Vote] Doxygen

[Christopher Jones]

On 26/6/17 4:43 pm, Joe Watkins wrote:

Morning,

I also voted no for similar reasons to Anatol.

This is not really a thing that needs a vote, this is a thing that requires
the handful of people who are actually able to document ZE to spend
considerable time doing so. In addition it requires a commitment from the
community of developers to continue to maintain, and introduce inline
documentation with new code.

Additionally, I'm a little concerned that an RFC that has the potential to
touch every single source file has gone to vote with a simple majority. It
would seem that we are deciding that new code must be documented in this
specific way, to say nothing of the massive task of documenting existing
code. That would seem to be a decision that could effect everybody that
works on PHP in perpetuity and a simple majority is nothing like a strong
enough consensus.

Cheers
Joe


I agree that although the intention is good, the burden on developers is likely
to cause it to be unsuccessful.  The current state of inline documentation is
partly the result of the culture of PHP, but also the general reluctance of
developers to create documentation :(

Chris



On Sat, Jun 24, 2017 at 10:59 PM, Anatol Belski  wrote:




-Original Message-
From: Fleshgrinder [mailto:p...@fleshgrinder.com]
Sent: Saturday, June 24, 2017 11:34 PM
To: php-internals ; Anatol Belski

Subject: Re: [PHP-DEV] [RFC] [Vote] Doxygen

On 6/24/2017 11:28 PM, Anatol Belski wrote:

I voted no, because it is too short term and I'd see a productivity
drop having such an obligation suddenly right in place for 7.2. To
implement the change, there's more than just to put the doc into the
source. Every piece of code needs to be revisited by someone who
understands it.

I'm not saying the current situation is better than the aim, but to be
realistic - the change needs a culture to be developed. It is clear,
that some know doxygen, but I believe maintaining the doc will be
still a huge effort for many contributors. If some patch were in place
- at least one would have a source for learning by watching, so it
would reduce the learn hurdle  Without being familiar with Doxygen
the actual productivity will for sure suffer.

Neither there's a patch covering at least the very core, nor there's a
strategy for the transition period. I can imagine, that even if the
RFC is voted positive, many contributors not familiar with doxygen
won't have time to complete the doc part. The intention good, but the
assertion might be hard. I might be wrong, but ATM I think the
intention is good, whereby the RFC implementation owes IMHO some
elaborated strategy.

Regards

Anatol


We are only voting that we want to use Doxygen for documentation as a
format, not that documentation is a must for PRs or anything. From the

RFC:

This RFC does not propose any big documentation fest where development
is halted and everybody starts writing documentation. Rather to start
documenting in the future, as well as while refactoring or rewriting
existing code.

Hence, it would be nice to write a little while one is working on

something

anyways.

There is no must to document!


Ok, that was my very concern. Documenting the existing code would also
need profound reviews.


There is a must that IF you document, that it must use Doxygen.

That's what we are voting on. Everybody has plenty of time to get

acquainted

with Doxygen and we can create follow-up RFCs with clearer rules on how

to

document (if need be).


I'd still see an issue, the formulation is a bit slack. If I don't have
to, probably I'd spare 10 minutes I'd have to spend, because a bug
investigation or implementation would take a triple time or more. Depending
on what it takes for me personally in the sum, it could be at least 1 hour
a week, most even 8 hours in a week, that's huge. I'd still say, it needs a
strategy and the community says it's a must. Otherwise, the doc might come
not from a person who implements or understands it. Or - the doc would only
reflect function signatures, which are anyway browsable with lxr, by grep
directly, or the code can be studied from the source.

Thanks

Anatol




--
http://twitter.com/ghrd


--
PHP Internals - PHP Runtime Development Mailing List
To unsubscribe, visit: http://www.php.net/unsub.php

Re: [PHP-DEV] [RFC] [Vote] Doxygen

[Rasmus Lerdorf]

No from me as well. This is wagging the dog by the tail. Picking a
documentation format is the very least of the concerns here. It would be
wonderful to have better internal API documentation, but putting up any
sort of structural restriction like limiting it to a specific header-based
format, isn't going to make such documentation more likely. I couldn't care
less which format such documentation is in. If the folks who are capable of
writing decent API docs want to do it in Microsoft Word, LaTeX or some
weird SGML format, great! Whatever format it might appear in we can use and
convert to whatever makes sense at that point.

-Rasmus

On Mon, Jun 26, 2017 at 5:26 AM, Kalle Sommer Nielsen  wrote:

> HI Joe,
>
> 2017-06-26 8:43 GMT+02:00 Joe Watkins :
> > Morning,
> >
> > I also voted no for similar reasons to Anatol.
> >
> > This is not really a thing that needs a vote, this is a thing that
> requires
> > the handful of people who are actually able to document ZE to spend
> > considerable time doing so. In addition it requires a commitment from the
> > community of developers to continue to maintain, and introduce inline
> > documentation with new code.
> >
> > Additionally, I'm a little concerned that an RFC that has the potential
> to
> > touch every single source file has gone to vote with a simple majority.
> It
> > would seem that we are deciding that new code must be documented in this
> > specific way, to say nothing of the massive task of documenting existing
> > code. That would seem to be a decision that could effect everybody that
> > works on PHP in perpetuity and a simple majority is nothing like a strong
> > enough consensus.
>
> I'm in the same boat as you and Anatol here.
>
> I think it is important to note that all who actively work on the
> Core/Engine have no except for Stas, which also should be a good
> indicator that we should be concerned.
> --
> regards,
>
> Kalle Sommer Nielsen
> ka...@php.net
>
> --
> PHP Internals - PHP Runtime Development Mailing List
> To unsubscribe, visit: http://www.php.net/unsub.php
>
>

[PHP-DEV] NEUTRAL Benchmark Results for PHP Master 2017-06-25

[lp_benchmark_robot]

Results for project PHP master, build date 2017-06-25 19:23:28-07:00
commit: 24030d5
previous commit:99b6119
revision date:  2017-06-25 19:39:13-04:00
environment:Haswell-EP
cpu:Intel(R) Xeon(R) CPU E5-2699 v3 @ 2.30GHz 2x18 cores, 
stepping 2, LLC 45 MB
mem:128 GB
os: CentOS 7.1
kernel: Linux 3.10.0-229.4.2.el7.x86_64

Baseline results were generated using release php-7.0.0, with hash 60fffd2 from
2015-12-01 04:16:47+00:00

---
benchmark   relative   change since   change since  
current rev run
std_dev*   last run   baseline  
   with PGO
---
:-|   Wordpress 4.2.2 cgi -T1  0.19%  0.73%  2.84%  
  8.35%
:-|   Drupal 7.36 cgi -T1  0.20%  0.77%  1.94%  
  5.51%
:-|   MediaWiki 1.23.9 cgi -T5000  0.07%  0.28%  3.24%  
  4.18%
:-|   bench.php cgi -T100  0.24% -0.45% 46.60%  
  3.63%
:-|  micro_bench.php cgi -T10  0.01% -0.42% 21.38%  
  2.91%
:-|  mandelbrot.php cgi -T100  0.02% -0.22% 44.42%  
 -2.32%
---

* Relative Standard Deviation (Standard Deviation/Average)

If this is not displayed properly please visit our results page here: 
http://languagesperformance.intel.com/neutral-benchmark-results-for-php-master-2017-06-25/

Note: Benchmark results for Wordpress, Drupal, MediaWiki are measured in
fetches/second while all others are measured in seconds.
More details on measurements methodology at: 
https://01.org/lp/documentation/php-environment-setup.

Subject Label Legend:
Attributes are determined based on the performance evolution of the workloads
compared to the previous measurement iteration.
NEUTRAL: performance did not change by more than 1% for any workload
GOOD: performance improved by more than 1% for at least one workload and there
is no regression greater than 1%
BAD: performance dropped by more than 1% for at least one workload and there is
no improvement greater than 1%
UGLY: performance improved by more than 1% for at least one workload and also
dropped by more than 1% for at least one workload


Our lab does a nightly source pull and build of the PHP project and measures
performance changes against the previous stable version and the previous nightly
measurement. This is provided as a service to the community so that quality
issues with current hardware can be identified quickly.

Intel technologies' features and benefits depend on system configuration and may
require enabled hardware, software or service activation. Performance varies
depending on system configuration.


-- 
PHP Internals - PHP Runtime Development Mailing List
To unsubscribe, visit: http://www.php.net/unsub.php

[PHP-DEV] Karma to edit LDAP_EXOP-RFC

[Andreas Heigl]

Hi All.

I'd like to edit the LDAP-EXOP RFC[1]that Côme just created as we'Re
both working on that.

Would it be possible to grant me karma for that?

Thanks and Cheers

Andreas

[1] https://wiki.php.net/rfc/ldap_exop
-- 
  ,,,
 (o o)
+-ooO-(_)-Ooo-+
| Andreas Heigl   |
| mailto:andr...@heigl.org  N 50°22'59.5" E 08°23'58" |
| http://andreas.heigl.org   http://hei.gl/wiFKy7 |
+-+
| http://hei.gl/root-ca   |
+-+



signature.asc
Description: OpenPGP digital signature

Re: [PHP-DEV] [RFC] [Vote] Doxygen

[Kalle Sommer Nielsen]

HI Joe,

2017-06-26 8:43 GMT+02:00 Joe Watkins :
> Morning,
>
> I also voted no for similar reasons to Anatol.
>
> This is not really a thing that needs a vote, this is a thing that requires
> the handful of people who are actually able to document ZE to spend
> considerable time doing so. In addition it requires a commitment from the
> community of developers to continue to maintain, and introduce inline
> documentation with new code.
>
> Additionally, I'm a little concerned that an RFC that has the potential to
> touch every single source file has gone to vote with a simple majority. It
> would seem that we are deciding that new code must be documented in this
> specific way, to say nothing of the massive task of documenting existing
> code. That would seem to be a decision that could effect everybody that
> works on PHP in perpetuity and a simple majority is nothing like a strong
> enough consensus.

I'm in the same boat as you and Anatol here.

I think it is important to note that all who actively work on the
Core/Engine have no except for Stas, which also should be a good
indicator that we should be concerned.
-- 
regards,

Kalle Sommer Nielsen
ka...@php.net

-- 
PHP Internals - PHP Runtime Development Mailing List
To unsubscribe, visit: http://www.php.net/unsub.php

Re: [PHP-DEV] PHP-LDAP EXOP support

[Kalle Sommer Nielsen]

Hi Andreas

2017-06-26 12:45 GMT+02:00 Andreas Heigl :
> The first possible release IMHO would be PHP.Next (sadly…), as there's
> already been a feature-freeze for PHP 7.2…

The feature freeze comes on July 20th, as per the wiki:
https://wiki.php.net/todo/php72

It is tight, but still possible to get features added =)

-- 
regards,

Kalle Sommer Nielsen
ka...@php.net

--
PHP Internals - PHP Runtime Development Mailing List
To unsubscribe, visit: http://www.php.net/unsub.php

Re: [PHP-DEV] PHP-LDAP EXOP support

[Andreas Heigl]

Hi Côme.


Am 26.06.17 um 11:34 schrieb Côme Chilliet:
> Hello,
> 
> Some time ago, someone said on the tracker that there was an up to date patch 
> for php-ldap exop and controls: https://bugs.php.net/bug.php?id=69445
> It appeared the code was in fact not up to date, at least not for PHP7.
> 
> But it was enough to make me try again to work from there to add EXOP support 
> to PHP-LDAP, so I extracted the part about EXOP from the patch and worked 
> from there to have something working with current master.
> The result is there for now: https://github.com/MCMic/php-src/tree/ldap_exop

Thanks for that work!
> 
> At least the methods for passwd and whoami EXOPs are working fine.
> 
> Which PHP release should a change like that target?

The first possible release IMHO would be PHP.Next (sadly…), as there's
already been a feature-freeze for PHP 7.2…
While that means that we have to wait another year until that feature
comes into production it also means that we might be able to have a more
conscise exop-handling for ldap by then…
> Do I need to open an RFC for these methods?

As we add functionality to the language we should have one… shouldn't we?
> 
> For now I just fixed code from the original patch mainly but I would like to 
> rework the API as I’m not convinced by the current state.
> ldap_exop and ldap_parse_exop API seems reasonable, but ldap_exop expects ber 
> encoded data as request data and I’m not sure how to create that.
> I think we should add a PHP method to ber encode, or change ldap_exop to 
> accept an other format and ber encode internally.
> For the helper methods for whoami and passwd, I’m a bit puzzled.
> They can work like this now:
> 
> ldap_exop_whoami($link, $authzid); // This return TRUE upon success or FALSE 
> otherwise
> $r = ldap_exop_whoami($link); // This return a result object you need to parse
> ldap_parse_exop_whoami($link, $r, $authzid); // This will parse the result 
> object and fill the third param with the result
> 
> I would go for something a lot simpler like ldap_exop_whoami($link) directly 
> returning the string result, or FALSE if it fails.
> 
> For ldap_exop_passwd, I would go for ldap_exop_passwd($link, $user, $oldpw, 
> $newpw) which would return FALSE on failure, TRUE on success with a new 
> password, or the generated password if $newpw is empty.
> 
> So I would ditch ldap_parse_exop_whoami and ldap_parse_exop_passwd. People 
> can use ldap_exop and ldap_parse_exop if they want to work with result 
> objects.
> I guess we will also need constants for OID of all known EXOP operations out 
> there.

As already mentioned on IRC I'm much more in favour of keeping the
naming more simple and use ldap_whoami and ldap_passwd instead of the
ldap_exop_whoami and ldap_Exop_passwd as there is no exop-parameter
necessary. Though we need to add the requirement of the server handling
that to the docs!

I'd use the _exop_ part only for functions that actually *need* an
exop-parameter.

Cheers

Andreas


-- 
  ,,,
 (o o)
+-ooO-(_)-Ooo-+
| Andreas Heigl   |
| mailto:andr...@heigl.org  N 50°22'59.5" E 08°23'58" |
| http://andreas.heigl.org   http://hei.gl/wiFKy7 |
+-+
| http://hei.gl/root-ca   |
+-+


0x5BFCE472.asc
Description: application/pgp-keys


signature.asc
Description: OpenPGP digital signature

[PHP-DEV] PHP-LDAP EXOP support

[Côme Chilliet]

Hello,

Some time ago, someone said on the tracker that there was an up to date patch 
for php-ldap exop and controls: https://bugs.php.net/bug.php?id=69445
It appeared the code was in fact not up to date, at least not for PHP7.

But it was enough to make me try again to work from there to add EXOP support 
to PHP-LDAP, so I extracted the part about EXOP from the patch and worked from 
there to have something working with current master.
The result is there for now: https://github.com/MCMic/php-src/tree/ldap_exop

At least the methods for passwd and whoami EXOPs are working fine.

Which PHP release should a change like that target?
Do I need to open an RFC for these methods?

For now I just fixed code from the original patch mainly but I would like to 
rework the API as I’m not convinced by the current state.
ldap_exop and ldap_parse_exop API seems reasonable, but ldap_exop expects ber 
encoded data as request data and I’m not sure how to create that.
I think we should add a PHP method to ber encode, or change ldap_exop to accept 
an other format and ber encode internally.
For the helper methods for whoami and passwd, I’m a bit puzzled.
They can work like this now:

ldap_exop_whoami($link, $authzid); // This return TRUE upon success or FALSE 
otherwise
$r = ldap_exop_whoami($link); // This return a result object you need to parse
ldap_parse_exop_whoami($link, $r, $authzid); // This will parse the result 
object and fill the third param with the result

I would go for something a lot simpler like ldap_exop_whoami($link) directly 
returning the string result, or FALSE if it fails.

For ldap_exop_passwd, I would go for ldap_exop_passwd($link, $user, $oldpw, 
$newpw) which would return FALSE on failure, TRUE on success with a new 
password, or the generated password if $newpw is empty.

So I would ditch ldap_parse_exop_whoami and ldap_parse_exop_passwd. People can 
use ldap_exop and ldap_parse_exop if they want to work with result objects.
I guess we will also need constants for OID of all known EXOP operations out 
there.

Côme

--
PHP Internals - PHP Runtime Development Mailing List
To unsubscribe, visit: http://www.php.net/unsub.php

Re: [PHP-DEV] [RFC] [Vote] Doxygen

[Joe Watkins]

Morning,

I also voted no for similar reasons to Anatol.

This is not really a thing that needs a vote, this is a thing that requires
the handful of people who are actually able to document ZE to spend
considerable time doing so. In addition it requires a commitment from the
community of developers to continue to maintain, and introduce inline
documentation with new code.

Additionally, I'm a little concerned that an RFC that has the potential to
touch every single source file has gone to vote with a simple majority. It
would seem that we are deciding that new code must be documented in this
specific way, to say nothing of the massive task of documenting existing
code. That would seem to be a decision that could effect everybody that
works on PHP in perpetuity and a simple majority is nothing like a strong
enough consensus.

Cheers
Joe

On Sat, Jun 24, 2017 at 10:59 PM, Anatol Belski  wrote:

>
>
> > -Original Message-
> > From: Fleshgrinder [mailto:p...@fleshgrinder.com]
> > Sent: Saturday, June 24, 2017 11:34 PM
> > To: php-internals ; Anatol Belski
> > 
> > Subject: Re: [PHP-DEV] [RFC] [Vote] Doxygen
> >
> > On 6/24/2017 11:28 PM, Anatol Belski wrote:
> > > I voted no, because it is too short term and I'd see a productivity
> > > drop having such an obligation suddenly right in place for 7.2. To
> > > implement the change, there's more than just to put the doc into the
> > > source. Every piece of code needs to be revisited by someone who
> > > understands it.
> > >
> > > I'm not saying the current situation is better than the aim, but to be
> > > realistic - the change needs a culture to be developed. It is clear,
> > > that some know doxygen, but I believe maintaining the doc will be
> > > still a huge effort for many contributors. If some patch were in place
> > > - at least one would have a source for learning by watching, so it
> > > would reduce the learn hurdle  Without being familiar with Doxygen
> > > the actual productivity will for sure suffer.
> > >
> > > Neither there's a patch covering at least the very core, nor there's a
> > > strategy for the transition period. I can imagine, that even if the
> > > RFC is voted positive, many contributors not familiar with doxygen
> > > won't have time to complete the doc part. The intention good, but the
> > > assertion might be hard. I might be wrong, but ATM I think the
> > > intention is good, whereby the RFC implementation owes IMHO some
> > > elaborated strategy.
> > >
> > > Regards
> > >
> > > Anatol
> > >
> >
> > We are only voting that we want to use Doxygen for documentation as a
> > format, not that documentation is a must for PRs or anything. From the
> RFC:
> >
> > > This RFC does not propose any big documentation fest where development
> > > is halted and everybody starts writing documentation. Rather to start
> > > documenting in the future, as well as while refactoring or rewriting
> > > existing code.
> >
> > Hence, it would be nice to write a little while one is working on
> something
> > anyways.
> >
> > There is no must to document!
> >
> Ok, that was my very concern. Documenting the existing code would also
> need profound reviews.
>
> > There is a must that IF you document, that it must use Doxygen.
> >
> > That's what we are voting on. Everybody has plenty of time to get
> acquainted
> > with Doxygen and we can create follow-up RFCs with clearer rules on how
> to
> > document (if need be).
> >
> I'd still see an issue, the formulation is a bit slack. If I don't have
> to, probably I'd spare 10 minutes I'd have to spend, because a bug
> investigation or implementation would take a triple time or more. Depending
> on what it takes for me personally in the sum, it could be at least 1 hour
> a week, most even 8 hours in a week, that's huge. I'd still say, it needs a
> strategy and the community says it's a must. Otherwise, the doc might come
> not from a person who implements or understands it. Or - the doc would only
> reflect function signatures, which are anyway browsable with lxr, by grep
> directly, or the code can be studied from the source.
>
> Thanks
>
> Anatol
>
>