[RFC] [Discussion] Using and Mentioning Third-party Packages in PHP Documentation and Web Projects

3 months ago by Jim Winstead — view source

unread

Hi,

Another RFC around process: https://wiki.php.net/rfc/web-and-doc-use-not-endorsement

Feedback would be appreciated. My intention is to start voting on September 9th unless there is still ongoing discussion.

Thanks.

Jim

3 months ago by Deleu — view source

unread

Hi Jim!

Hi,

Another RFC around process:
https://wiki.php.net/rfc/web-and-doc-use-not-endorsement

Feedback would be appreciated. My intention is to start voting on
September 9th unless there is still ongoing discussion.

Thanks.

Jim

Unfortunately I can't vote but I'm rooting big time for this RFC big time.
I would however advocate for the use of slightly broader scope:

The web, documentation, infrastructure and any auxiliary projects within
the PHP Project can use or document the existence of third-party PHP
projects as part of their roles in supporting the overall PHP community.
Such use does not represent endorsement of those third-party projects by
the PHP Project.

--
Marco Deleu

3 months ago by Jim Winstead — view source

unread

Hi Jim!

__
Hi,

Another RFC around process: https://wiki.php.net/rfc/web-and-doc-use-not-endorsement

Feedback would be appreciated. My intention is to start voting on September 9th unless there is still ongoing discussion.

Thanks.

Jim

Unfortunately I can't vote but I'm rooting big time for this RFC big time. I would however advocate for the use of slightly broader scope:

The web, documentation, infrastructure and any auxiliary projects within the PHP Project can use or document the existence of third-party PHP projects as part of their roles in supporting the overall PHP community. Such use does not represent endorsement of those third-party projects by the PHP Project.

Good idea, I have tweaked that text as suggested.

Thanks.

Jim

3 months ago by Bob Weinand — view source

unread

Hey Jim,

Hi,

Another RFC around process:
https://wiki.php.net/rfc/web-and-doc-use-not-endorsement

Feedback would be appreciated. My intention is to start voting on
September 9th unless there is still ongoing discussion.

Thanks.

Jim

Thanks for bringing this up - I also suggest that we make this a binary
choice - either we adopt the proposed language or its opposite.

I.e. a rejection of this should codify that statement in the negative.

I do in particular reject the notion that we should document third-party
projects (usage for our infra is fine).

The point of the PHP documentation is to describe the PHP runtime and
PECL extensions, which are both officially distributed through php.net.

Anything not related to these does not belong into the manual, much less
into core documentation (like language/oop5 autoload.xml, to take the
example from https://github.com/php/doc-en/pull/3677/files).

Changing this current unwritten rule is an invitation to implicitly
promote specific projects. The question is really where does it end?
Would we for example also mention PSRs as "widely followed guidelines
for interoperability" or something? It's a strong invitation for some
scope creep.

As such I strongly condemn the idea of inclusion of this guideline.

There are, ultimately, enough ways for people to learn about the PHP
ecosystem, the php.net documentation is none of them. If I go to
php.net, it's because I want to learn about the runtime, not its ecosystem.

Bob

3 months ago by Larry Garfield — view source

unread

Hey Jim,

Hi,

Another RFC around process: https://wiki.php.net/rfc/web-and-doc-use-not-endorsement

Feedback would be appreciated. My intention is to start voting on September 9th unless there is still ongoing discussion.

Thanks.

Jim

Thanks for bringing this up - I also suggest that we make this a binary
choice - either we adopt the proposed language or its opposite.

I.e. a rejection of this should codify that statement in the negative.

I do in particular reject the notion that we should document
third-party projects (usage for our infra is fine).

The point of the PHP documentation is to describe the PHP runtime and
PECL extensions, which are both officially distributed through php.net.

Anything not related to these does not belong into the manual, much
less into core documentation (like language/oop5 autoload.xml, to take
the example from https://github.com/php/doc-en/pull/3677/files).

Changing this current unwritten rule is an invitation to implicitly
promote specific projects. The question is really where does it end?
Would we for example also mention PSRs as "widely followed guidelines
for interoperability" or something? It's a strong invitation for some
scope creep.

As such I strongly condemn the idea of inclusion of this guideline.

There are, ultimately, enough ways for people to learn about the PHP
ecosystem, the php.net documentation is none of them. If I go to
php.net, it's because I want to learn about the runtime, not its
ecosystem.

There's two separate questions here, I think, which should probably be addressed separately.

One is whether PHP.net code can use third party libraries (and be open about it). Eg, would it be OK if Phd (the documentation compiler) used Composer for autoloading? Used symfony/serializer or crell/serde in some way? Used ramsey/uuid as an internal implementation detail? Right now, the answer is de facto no, with some unclear exceptions. I very firmly believe the answer should be a strong YES, or at least a "mostly", because doing otherwise hamstrings our ability to actually do the much-needed work of keeping the infra going.

The other is whether the documentation should recognize the rest of the ecosystem, or be "just" "things in the php org on Github." I can definitely see the potential for scope creep here, and we should be mindful of that, but at the same time, having an official first-party "where to start with the ecosystem" place is extremely valuable! Sending someone into PHP without recognizing the existence of Composer, which has basically no competition, is doing them a gross disservice. Telling them about PHPUnit, which is overwhelmingly the most popular testing system but there are others (mostly built on top of it), I would lean yes but I can see the argument against. Recommending a template engine and listing just Twig and Blade but not Latte, for example, I can totally see where that becomes an issue and why we wouldn't want to do that.

My recommendation on the GitHub thread was, and still is, to make it a one-off vote in each case. We had a one-off vote to recognize the Foundation on php.net and direct people to it. I'd favor a one-off vote to allow talking about Composer/Packagist in the docs, and I would vote yes on it. I'd probably vote no for a one-off vote to mention Twig.

PHP.net is the starting point for people in the PHP ecosystem, good or bad. We don't need to take ownership of the whole ecosystem or documentation therein, but at least providing jumping off points to obvious sources (Composer/Packagist, phptherightway.com, etc.) would be doing a good service for our users.

--Larry Garfield

3 months ago by Deleu — view source

unread

Thanks for bringing this up - I also suggest that we make this a binary
choice - either we adopt the proposed language or its opposite.

I.e. a rejection of this should codify that statement in the negative.

I do in particular reject the notion that we should document third-party
projects (usage for our infra is fine).

The point of the PHP documentation is to describe the PHP runtime and PECL
extensions, which are both officially distributed through php.net.

Anything not related to these does not belong into the manual, much less
into core documentation (like language/oop5 autoload.xml, to take the
example from https://github.com/php/doc-en/pull/3677/files).

Changing this current unwritten rule is an invitation to implicitly
promote specific projects. The question is really where does it end? Would
we for example also mention PSRs as "widely followed guidelines for
interoperability" or something? It's a strong invitation for some scope
creep.

As such I strongly condemn the idea of inclusion of this guideline.

There are, ultimately, enough ways for people to learn about the PHP
ecosystem, the php.net documentation is none of them. If I go to php.net,
it's because I want to learn about the runtime, not its ecosystem.

Bob

Since your message was somewhat ambiguous to me, I would like to take this
opportunity to request clarification from Jim.

I read this RFC as an opportunity to allow community-driven PHP projects to
be embraced when it suits PHP's internals needs. For instance, I remember a
few years ago a conversation about rebuilding the php.net website. The
current "unwritten" rule was used to impose that a new PHP website could
not use any existing PHP Framework as to not "endorse" any particular
project. Same thing goes for the RFC Voting process, PSRs, Composer, etc.

In a way, I agree with Bob's take that the php.net documentation should not
be used to document 3rd-party tooling, but my interpretation of the RFC
has nothing to do with documenting 3rd-party tools but instead its about
mentioning or even relying on them.

Current discussion about Generics going on talks a lot about phpstan and
psalm and whatever comes out of the work put into Generics, I would
definitely be in favour of PHP docs mentioning how Generics is already
present today with those tools. Current work-in-progress from the
Foundation in regards to revamping pecl involves (as far as I know)
providing PHP Extensions via Composer which would be something that said
"unwritten" rule could be mentioned for opposing such approach. There's
also PHP community members that would be willing to work on a new RFC
automation tool to improve on the process that has recently been mentioned
as "suboptimal" [1]. Such community members would certainly opt to build
this upon Symfony, Laravel, Slim or anything more convenient than vanilla
PHP and such "unwritten" rule keeps us chained to suboptimal infrastructure.

[1] https://externals.io/message/124843#124860

--
Marco Deleu

3 months ago by Derick Rethans — view source

unread

Thanks for bringing this up - I also suggest that we make this a
binary choice - either we adopt the proposed language or its
opposite.

I.e. a rejection of this should codify that statement in the
negative.

I do in particular reject the notion that we should document
third-party projects (usage for our infra is fine).

The point of the PHP documentation is to describe the PHP runtime
and PECL extensions, which are both officially distributed through
php.net.

Anything not related to these does not belong into the manual, much
less into core documentation (like language/oop5 autoload.xml, to
take the example from
https://github.com/php/doc-en/pull/3677/files).

Changing this current unwritten rule is an invitation to implicitly
promote specific projects. The question is really where does it end?
Would we for example also mention PSRs as "widely followed
guidelines for interoperability" or something? It's a strong
invitation for some scope creep.

As such I strongly condemn the idea of inclusion of this guideline.

There are, ultimately, enough ways for people to learn about the PHP
ecosystem, the php.net documentation is none of them. If I go to
php.net, it's because I want to learn about the runtime, not its
ecosystem.

Since your message was somewhat ambiguous to me, I would like to take
this opportunity to request clarification from Jim.

I read this RFC as an opportunity to allow community-driven PHP
projects to be embraced when it suits PHP's internals needs. For
instance, I remember a few years ago a conversation about rebuilding
the php.net website. The current "unwritten" rule was used to impose
that a new PHP website could not use any existing PHP Framework as to
not "endorse" any particular project. Same thing goes for the RFC
Voting process, PSRs, Composer, etc.

I think there is a difference between "using existing packages to make
our life easier" and "we use this fully fledged framework". The latter
should still not be a reasonable outcome here.

In a way, I agree with Bob's take that the php.net documentation
should not be used to document 3rd-party tooling, but my
interpretation of the RFC has nothing to do with documenting 3rd-party
tools but instead its about mentioning or even relying on them.

No, it absolutely has something to do with that. There is no mention of
Composer on php.net. That is ludicrous.

Documenting proprietary installers (such as AMPSS as raised in
https://github.com/php/doc-en/pull/1674) is probably something I won't
favour.

Explaining how to install PHP with homebrew, apt or yum makes perfect
sense to me. Nobody really ought to go to www.php.net/download and
compile PHP themselves. But that's the only installation instructions
that we have.

cheers,
Derick

3 months ago by Christoph M. Becker — view source

unread

Explaining how to install PHP with homebrew, apt or yum makes perfect
sense to me. Nobody really ought to go to www.php.net/download and
compile PHP themselves. But that's the only installation instructions
that we have.

Well, it's not that bad; there is some info available at
https://www.php.net/manual/en/install.php (although that needs to be
updated and generally improved).

And yeah, I guess that there are users who do not even know what a
tarball is, let alone understand the ./configure, make, make install
workflow.

And for Windows users, the situation might be worse, since these are
used to download some installer, execute it, and are ready to go.
Unless they are aware of XAMPP (which is shortly mentioned in the
installation guide), or some such, they probably go somewhere else. And
that is so easy: you just type "I hate PHP" and press ENTER, and are
redirected to a nice site, where you hover over "Downloads" and get your
installer with a single click.

Christoph

3 months ago by Derick Rethans — view source

unread

Another RFC around process:
https://wiki.php.net/rfc/web-and-doc-use-not-endorsement

Feedback would be appreciated. My intention is to start voting on
September 9th unless there is still ongoing discussion.

Thanks for bringing this up - I also suggest that we make this a
binary choice - either we adopt the proposed language or its opposite.

I.e. a rejection of this should codify that statement in the negative.

I do in particular reject the notion that we should document
third-party projects (usage for our infra is fine).

I think this is short-sighted.

Currently, our main website, php.net, does not have useful installation
instructions.

We have a "Download" tab, which points to tarballs. Who still installs
tarballs like this? Nobody does. It's either distribution packages, or
installers such as XAMPP, or MAMP, or whatever.

We are doing our (potential) users a disservice by not explaining the
reasonable ways of installing PHP.

We should replace our "Download" page with something that people would
actually benefit from.

Just like our home page is just boring release announcements. This
should have much more interesting stuff such as how, and when, to use
the great new features that we have been adding in the last decade.

The point of the PHP documentation is to describe the PHP runtime and
PECL extensions, which are both officially distributed through
php.net.

I also think we are not doing PHP a favour by refusing to mention the
main way how developers now install libraries: Composer. It doesn't have
to be a comprehensive guide, but it is ludicrous to not even have a page
in our documentation that describes how modern PHP applications get (and
should) get bootstrapped.

We will have the same argument eith PIE (working title) soon too.

Should we promote a specific framework? No, probably not. Should we
endeavour to rewrite all of our internal stuff in Symfony, or Laravel,
or Nette, or Zend Framework. Also very much not.

But not even have a link to Composer and how it used for modern PHP
development is just plain stupid, like having a most light hint at how
you effectively debug PHP code.

Our users want to know how to do things properly, and the
documentation needs to reflect that.

Anything not related to these does not belong into the manual, much
less into core documentation (like language/oop5 autoload.xml, to take
the example from https://github.com/php/doc-en/pull/3677/files).

Where PHP originally had the arguably the best documentation, this has
slipped.

Our langauge sections in the manual are dry, and only explain what the
language syntax are.

It doesn't describe how these features are useful, when you might want
to use them, what related development patterns and practises are.

This absolutely belongs in our documentation.

Changing this current unwritten rule is an invitation to implicitly
promote specific projects. The question is really where does it end?
Would we for example also mention PSRs as "widely followed guidelines
for interoperability" or something? It's a strong invitation for some
scope creep.

Why not? It's how modern PHP development works.

We don't have to go into the intricacies on how PSRs get developed, but
not even mentioning best practises doesn't seem particularly useful.

There are, ultimately, enough ways for people to learn about the PHP
ecosystem, the php.net documentation is none of them. If I go to
php.net, it's because I want to learn about the runtime, not its
ecosystem.

And that is how you will find that the "new" languages will "win". If we
don't promote how modern PHP Development works, then there will be more
"PHP, a fractal of bad design" articles to come for decades.

We must do better than this. It probably doesn't all need to be in the
documentation (doc-en), but it absolutely belongs on our website.

cheers,
Derick

3 months ago by Nick Lockheart — view source

unread

Just like our home page is just boring release announcements. This
should have much more interesting stuff such as how, and when, to use
the great new features that we have been adding in the last decade.

I would add that there are lots of features where the PHP manual says
how the functions work, but not how all the parts fit together.

There really should be documentation on "why do I need/want this" and
"what can I do with it"?

Reflection: When and why do we want to use this? What useful problem
does it solve and where is a working example?

Attributes: What problem does this solve and why would a developer need
this?

Fibers: When and how do we use this? And what is the exact list of
"fiberable" things? ie. Can we fiber a PDO SQL request?

And then there's stuff like SSH2, that's just a bunch of function
references, and there is no official, complete documentation on how
to do the entire process of connecting to a remote server over SSH,
issuing commands, checking the response of those commands (1 or 0
return value), and so on.

I think some more tutorial type documentation would be great from
PHP. How to put all the parts together for a complete solution to some
real world useful problem.

3 months ago by John Coggeshall — view source

unread

And that is how you will find that the "new" languages will "win". If we
don't promote how modern PHP Development works, then there will be more
"PHP, a fractal of bad design" articles to come for decades.

We must do better than this. It probably doesn't all need to be in the
documentation (doc-en), but it absolutely belongs on our website.

Hear Hear Derick!!
I am not advocating that php.net put its finger on the scale in favor of Laravel over others with this comment, but why php.net does not have a documentation analog similar to how Laravel's documentation is set up is beyond me. Useful installation instructions, sections on "How do I do database stuff", "Security", "Filtering Data", "Installing third party packages" etc... there are too many people who have embedded in their brains that PHP is a badly designed language because we don't teach or even advertise to people how to write good PHP code... as others have mentioned as an example, the lack of even a mention of composer on php.net is mind-blowing.
As Derick said, back 20+ years ago PHP had amazing documentation for the times -- miles ahead IMO than most open source projects. But the world has moved on, developers want and need higher level documentation that is more opinionated on not just the dry APIs available you might use to connect to a database (for example), but how to properly connect to a database. Back 20 years ago we had companies like Zend around who devoted considerable resources to filling that gap for the community (along with O'Reilly, etc.) but those entities are gone now and it is up to the project to pick up the slack.
I also think it's a mistake to get too caught up with the concept of "endorsements" and people worrying that "oh gosh if php.net talks about Laravel and Zend Framework then that means something bad for XYZ framework" (pick your favoriate techs here). It's easily solved by having a section on "Popular PHP Frameworks" that explains the concept that PHP as a language doesn't embrace any particular framework, the importance that you do generally want to embrace a framework to do anything serious, and provide a list of popular ones that people commonly turn to when building their apps. As for using a framework or any other PHP-related tech in the project's codebases... I think we're grossly overestimating how much weight that decision would carry with the PHP community at large. Short of the PHP Project stating "X is the official framework of PHP" (and especially if we say "We don't have an official framework but here are good options that are very popular" instead), the concern over the
appearance of endorsements at this point is really an invented issue rooted at least in part by historic concerns that simply don't exist anymore.
Coogle

3 months ago by Rob Landers — view source

unread

And that is how you will find that the "new" languages will "win". If we
don't promote how modern PHP Development works, then there will be more
"PHP, a fractal of bad design" articles to come for decades.

We must do better than this. It probably doesn't all need to be in the
documentation (doc-en), but it absolutely belongs on our website.

Hear Hear Derick!!

I am not advocating that php.net put its finger on the scale in favor of Laravel over others with this comment, but why php.net does not have a documentation analog similar to how Laravel's documentation is set up is beyond me. Useful installation instructions, sections on "How do I do database stuff", "Security", "Filtering Data", "Installing third party packages" etc... there are too many people who have embedded in their brains that PHP is a badly designed language because we don't teach or even advertise to people how to write good PHP code... as others have mentioned as an example, the lack of even a mention of composer on php.net is mind-blowing.

As Derick said, back 20+ years ago PHP had amazing documentation for the times -- miles ahead IMO than most open source projects. But the world has moved on, developers want and need higher level documentation that is more opinionated on not just the dry APIs available you might use to connect to a database (for example), but how to properly connect to a database. Back 20 years ago we had companies like Zend around who devoted considerable resources to filling that gap for the community (along with O'Reilly, etc.) but those entities are gone now and it is up to the project to pick up the slack.

I also think it's a mistake to get too caught up with the concept of "endorsements" and people worrying that "oh gosh if php.net talks about Laravel and Zend Framework then that means something bad for XYZ framework" (pick your favoriate techs here). It's easily solved by having a section on "Popular PHP Frameworks" that explains the concept that PHP as a language doesn't embrace any particular framework, the importance that you do generally want to embrace a framework to do anything serious, and provide a list of popular ones that people commonly turn to when building their apps. As for using a framework or any other PHP-related tech in the project's codebases... I think we're grossly overestimating how much weight that decision would carry with the PHP community at large. Short of the PHP Project stating "X is the official framework of PHP" (and especially if we say "We don't have an official framework but here are good options that are very popular" instead), the concern over the appearance of endorsements at this point is really an invented issue rooted at least in part by historic concerns that simply don't exist anymore.

Coogle

I agree with this to a point. What if I want my newish framework listed on the page? What are the qualifications for being listed (or unlisted) there? Can anyone add their own framework?

If anyone can add something to the list, then it eventually will become as overwhelming as https://github.com/uhub/awesome-php and if there are strict qualification requirements, the list needs to be reviewed periodically to remove projects that no longer meet those criteria.

— Rob

3 months ago by John Coggeshall — view source

unread

I agree with this to a point. What if I want my newish framework listed on the page? What are the qualifications for being listed (or unlisted) there? Can anyone add their own framework?
Personally I say put the top 5 by Github stars on a page by themselves, and have a secondary page ranked by star rating for all the rest -- unless at some point in the future star rating becomes an inaccurate representation and at that point we can revisit the subject. Let others decide what "popular" means.
If anyone can add something to the list, then it eventually will become as overwhelming as https://github.com/uhub/awesome-php and if there are strict qualification requirements, the list needs to be reviewed periodically to remove projects that no longer meet those criteria.
I agree -- The whole point is to be useful and enlightening.
Coogle

3 months ago by Bilge — view source

unread

If anyone can add something to the list, then it eventually will
become as overwhelming as https://github.com/uhub/awesome-php
FYI, that's not the Awesome PHP list, this is:
https://github.com/ziadoz/awesome-php. That other one doesn't even look
curated.

3 months ago by Larry Garfield — view source

unread

And that is how you will find that the "new" languages will "win". If we
don't promote how modern PHP Development works, then there will be more
"PHP, a fractal of bad design" articles to come for decades.

We must do better than this. It probably doesn't all need to be in the
documentation (doc-en), but it absolutely belongs on our website.

Hear Hear Derick!!

I am not advocating that php.net put its finger on the scale in favor
of Laravel over others with this comment, but why php.net does not have
a documentation analog similar to how Laravel's documentation is set up
is beyond me. Useful installation instructions, sections on "How do I
do database stuff", "Security", "Filtering Data", "Installing third
party packages" etc... there are too many people who have embedded in
their brains that PHP is a badly designed language because we don't
teach or even advertise to people how to write good PHP code... as
others have mentioned as an example, the lack of even a mention of
composer on php.net is mind-blowing.

As Derick said, back 20+ years ago PHP had amazing documentation for
the times -- miles ahead IMO than most open source projects. But the
world has moved on, developers want and need higher level documentation
that is more opinionated on not just the dry APIs available you might
use to connect to a database (for example), but how to properly connect
to a database. Back 20 years ago we had companies like Zend around who
devoted considerable resources to filling that gap for the community
(along with O'Reilly, etc.) but those entities are gone now and it is
up to the project to pick up the slack.

I also think it's a mistake to get too caught up with the concept of
"endorsements" and people worrying that "oh gosh if php.net talks about
Laravel and Zend Framework then that means something bad for XYZ
framework" (pick your favoriate techs here). It's easily solved by
having a section on "Popular PHP Frameworks" that explains the concept
that PHP as a language doesn't embrace any particular framework, the
importance that you do generally want to embrace a framework to do
anything serious, and provide a list of popular ones that people
commonly turn to when building their apps. As for using a framework or
any other PHP-related tech in the project's codebases... I think we're
grossly overestimating how much weight that decision would carry with
the PHP community at large. Short of the PHP Project stating "X is the
official framework of PHP" (and especially if we say "We don't have an
official framework but here are good options that are very popular"
instead), the concern over the appearance of endorsements at this point
is really an invented issue rooted at least in part by historic
concerns that simply don't exist anymore.

Coogle

What a couple of people have touched on is that that all we have right now is a Reference, which is only one kind of documentation. The common zeitgeist these days says there's 4: https://diataxis.fr/

Tutorials
How-to guides
Explanation
Reference

We have a reference with gaps, and that's about it. In practice, it will be functionally impossible to write a meaningful tutorial or how-to guide that never mentions anything but php-src-provided code. Or at least the result would be sub-standard and doing the reader a disservice.

I don't think I'd support a list of "popular" frameworks, but mentioning Composer, Xdebug, and PHPUnit seems a requirement for a useful modern tutorial.

Admittedly, the docs team is very under-resourced right now and even the reference section has not-small holes, making maintaining even more types of documentation a potential challenge. That's something the Foundation could possibly help with. But that's not the topic at hand: The topic at hand is just "look, we should be able to mention Composer, Xdebug, and PHPUnit, OK?" On which I very much am in agreement.

--Larry Garfield

3 months ago by Nick Lockheart — view source

unread

What a couple of people have touched on is that that all we have
right now is a Reference, which is only one kind of documentation.
The common zeitgeist these days says there's 4: https://diataxis.fr/

Tutorials

How-to guides

Explanation

Reference

We have a reference with gaps, and that's about it. In practice, it
will be functionally impossible to write a meaningful tutorial or
how-to guide that never mentions anything but php-src-provided code.
Or at least the result would be sub-standard and doing the reader a
disservice.

I don't think I'd support a list of "popular" frameworks, but
mentioning Composer, Xdebug, and PHPUnit seems a requirement for a
useful modern tutorial.

Admittedly, the docs team is very under-resourced right now and even
the reference section has not-small holes, making maintaining even
more types of documentation a potential challenge. That's something
the Foundation could possibly help with. But that's not the topic at
hand: The topic at hand is just "look, we should be able to mention
Composer, Xdebug, and PHPUnit, OK?" On which I very much am in
agreement.

Since we are talking about 3rd party tools, is "documentation" not a
tool?

Could we have a section for "further learning" that links to books and
websites?

3 months ago by John Coggeshall — view source

unread

I don't think I'd support a list of "popular" frameworks, but mentioning Composer, Xdebug, and PHPUnit seems a requirement for a useful modern tutorial.

Can you explain your position more here, what exactly is your concern (if I captured it in my previous email -- why do you think I'm off base to say we're over-estimating the importance)?

Admittedly, the docs team is very under-resourced right now and even the reference section has not-small holes, making maintaining even more types of documentation a potential challenge. That's something the Foundation could possibly help with. But that's not the topic at hand: The topic at hand is just "look, we should be able to mention Composer, Xdebug, and PHPUnit, OK?" On which I very much am in agreement.
That's not the topic at hand -- the topic at hand is adopting the principle that:
"The web and documentation projects within the PHP Project can use or document the existence of third-party PHP projects as part of their roles in supporting the overall PHP community. Such use does not represent endorsement of those third-party projects by the PHP Project."
So that would include frameworks, etc. alongside composer, phpunit, etc.

3 months ago by Andreas Heigl — view source

unread

Hey all

Am 26.08.24 um 20:06 schrieb Bob Weinand:

Hey Jim,

Hi,

Another RFC around process:
https://wiki.php.net/rfc/web-and-doc-use-not-endorsement

Feedback would be appreciated. My intention is to start voting on
September 9th unless there is still ongoing discussion.

Thanks.

Jim

Thanks for bringing this up - I also suggest that we make this a binary
choice - either we adopt the proposed language or its opposite.

I.e. a rejection of this should codify that statement in the negative.

I do in particular reject the notion that we should document third-party
projects (usage for our infra is fine).

I see this a bid differently to be honest. While I understand that using
third party packages in our internal tools might make things easier in
the short term it will cause a lot or additional work in the long term.

Currently we have a lot of small scripts that do one thing. And they do
it for a long time with very little maintenance effort. Blowing these
scripts up with third-party libraries will mean that we will have to put
in much more maintenance effort for either keeping the dependencies up
to date or mostly rewriting the script the moment a change needs to
happen as the libraries will be outdated.

There are though some actual console applications like Pdt where it
might be valid to use third party dependencies. But also here I'd ask
whether the maintainability will be increased. A totally different
question though is whether we actually need to maintain a special tool
for building the docs or whether we can use a pre-existing tool for
that. I am mainly thinking about either phpDocumentor or a default
docbook renderer. But that is a totally differnt topic IMO.

So I'd see this exactly the other way around:

usage for infra needs very careful consideration to not increase the
maintenance-burden on those that actually 'do' the maintenance.

But mentioning - and encouraging - best practices for developing
PHP-Applications is something that the PHP-Project should actively provide.

The point of the PHP documentation is to describe the PHP runtime and
PECL extensions, which are both officially distributed through php.net.

Anything not related to these does not belong into the manual, much less
into core documentation (like language/oop5 autoload.xml, to take the
example from https://github.com/php/doc-en/pull/3677/files).

Changing this current unwritten rule is an invitation to implicitly
promote specific projects. The question is really where does it end?
Would we for example also mention PSRs as "widely followed guidelines
for interoperability" or something? It's a strong invitation for some
scope creep.

As such I strongly condemn the idea of inclusion of this guideline.

There are, ultimately, enough ways for people to learn about the PHP
ecosystem, the php.net documentation is none of them. If I go to
php.net, it's because I want to learn about the runtime, not its ecosystem.
If I go to PHP.net, I want to learn about PHP. As an end user I don't
really care whether it's the runtime internals or the ecosystem. It is a
manual for PHP. And as such it should provide me with what we consider
Best Practices.

My 0.02€ from having done some maintenance on php.net.

Cheers

Andreas

                                                           ,,,
                                                          (o o)

+---------------------------------------------------------ooO-(_)-Ooo-+
| Andreas Heigl |
| mailto:andreas@heigl.org N 50°22'59.5" E 08°23'58" |
| https://andreas.heigl.org |
+---------------------------------------------------------------------+
| https://hei.gl/appointmentwithandreas |
+---------------------------------------------------------------------+
| GPG-Key: https://hei.gl/keyandreasheiglorg |
+---------------------------------------------------------------------+

3 months ago by Christoph M. Becker — view source

unread

I see this a bid differently to be honest. While I understand that using
third party packages in our internal tools might make things easier in
the short term it will cause a lot or additional work in the long term.

Currently we have a lot of small scripts that do one thing. And they do
it for a long time with very little maintenance effort. Blowing these
scripts up with third-party libraries will mean that we will have to put
in much more maintenance effort for either keeping the dependencies up
to date or mostly rewriting the script the moment a change needs to
happen as the libraries will be outdated.

There are though some actual console applications like Pdt where it
might be valid to use third party dependencies. But also here I'd ask
whether the maintainability will be increased. A totally different
question though is whether we actually need to maintain a special tool
for building the docs or whether we can use a pre-existing tool for
that. I am mainly thinking about either phpDocumentor or a default
docbook renderer. But that is a totally differnt topic IMO.

So I'd see this exactly the other way around:

usage for infra needs very careful consideration to not increase the
maintenance-burden on those that actually 'do' the maintenance.

Well, the RFC is not about that projects should use some tools or
libraries or frameworks, but rather that they can choose to do so if
they deem it valuable. Of course, the projects should not only look at
the short term benefit, but also on the long term maintenance burden.

For instance, web-php introduced Composer about two years ago, and in
the following added support for php-cs-fixer and phpunit to be able to
enforce a certain coding style and to run some tests. The maintenance
burden appears to be low (and might be lowered by ignoring dependabot).

Or another example would be the php-sdk-binary-tools. That code base
had been originally developed for late PHP5 versions, and as such is
showing cracks, and given that it is not extensively used, some long
standing bugs have not even been noticed. Just by running some static
analysis I easily found a couple of minor and not so minor issues. I
consider it helpful to actually add some static analysis tool(s) to the
repo (instead of setting this up locally, and running only
occassionally), and maybe in the long run to also have some automated test.

Yet another example is web-pecl, which has quite some bugs, but
apparently nobody has a test environment set up, so fixing a bug may
introduce another (BTDT). Some tooling may be helpful there.

Note that I have no intentions of rewriting these projects on top of a
framework, but tooling and maybe a few libraries should make things
easier for the respective developers, even in the long run.

Christoph

3 months ago by Andreas Heigl — view source

unread

Hey Christoph, hey all.

Am 27.08.24 um 13:46 schrieb Christoph M. Becker:

I see this a bid differently to be honest. While I understand that using
third party packages in our internal tools might make things easier in
the short term it will cause a lot or additional work in the long term.

Currently we have a lot of small scripts that do one thing. And they do
it for a long time with very little maintenance effort. Blowing these
scripts up with third-party libraries will mean that we will have to put
in much more maintenance effort for either keeping the dependencies up
to date or mostly rewriting the script the moment a change needs to
happen as the libraries will be outdated.

There are though some actual console applications like Pdt where it
might be valid to use third party dependencies. But also here I'd ask
whether the maintainability will be increased. A totally different
question though is whether we actually need to maintain a special tool
for building the docs or whether we can use a pre-existing tool for
that. I am mainly thinking about either phpDocumentor or a default
docbook renderer. But that is a totally differnt topic IMO.

So I'd see this exactly the other way around:

usage for infra needs very careful consideration to not increase the
maintenance-burden on those that actually 'do' the maintenance.

Well, the RFC is not about that projects should use some tools or
libraries or frameworks, but rather that they can choose to do so if
they deem it valuable. Of course, the projects should not only look at
the short term benefit, but also on the long term maintenance burden.

For instance, web-php introduced Composer about two years ago, and in
the following added support for php-cs-fixer and phpunit to be able to
enforce a certain coding style and to run some tests. The maintenance
burden appears to be low (and might be lowered by ignoring dependabot).

Or another example would be the php-sdk-binary-tools. That code base
had been originally developed for late PHP5 versions, and as such is
showing cracks, and given that it is not extensively used, some long
standing bugs have not even been noticed. Just by running some static
analysis I easily found a couple of minor and not so minor issues. I
consider it helpful to actually add some static analysis tool(s) to the
repo (instead of setting this up locally, and running only
occassionally), and maybe in the long run to also have some automated test.

Yet another example is web-pecl, which has quite some bugs, but
apparently nobody has a test environment set up, so fixing a bug may
introduce another (BTDT). Some tooling may be helpful there.

Note that I have no intentions of rewriting these projects on top of a
framework, but tooling and maybe a few libraries should make things
easier for the respective developers, even in the long run.

I would like to differentiate between "tools" and "dependencies".

A tool is for me something that runs independently from the project it
is used on and in the end the language it is written in is irrelevant as
long as it does it's job. Static analysis tools like PHPStan or
CS-Checker like phpcs are such tools.

The fact that these tools are also written in PHP is a mere detail but
seems to be problematic. They could also be written in C, Go or Rust and
nobody would question their usage. This seems odd. And for me their
usage on anything related to php.net should under no circumstances be a
problem.

Dependencies on the other hand are something that can not be used on
it's own and something the project is (more or less) tightly coupled to.

Those are the ones I see problematic. But you are correct in stating
that the project does not have to use dependencies but can.

As long as code-reviews or similar things make sure that only reasonable
and absolutely necessary dependencies are used I have no issue with
that. While PIE is a good way of thinking sometimes the
maintenance-burden of NIH is lower.

My 0.02 €

Cheers

Andreas

--
,,,
(o o)
+---------------------------------------------------------ooO-(_)-Ooo-+
| Andreas Heigl |
| mailto:andreas@heigl.org N 50°22'59.5" E 08°23'58" |
| https://andreas.heigl.org |
+---------------------------------------------------------------------+
| https://hei.gl/appointmentwithandreas |
+---------------------------------------------------------------------+
| GPG-Key: https://hei.gl/keyandreasheiglorg |
+---------------------------------------------------------------------+

3 months ago by Jim Winstead — view source

unread

I see this a bid differently to be honest. While I understand that using
third party packages in our internal tools might make things easier in
the short term it will cause a lot or additional work in the long term.

Currently we have a lot of small scripts that do one thing. And they do
it for a long time with very little maintenance effort. Blowing these
scripts up with third-party libraries will mean that we will have to put
in much more maintenance effort for either keeping the dependencies up
to date or mostly rewriting the script the moment a change needs to
happen as the libraries will be outdated.

There are though some actual console applications like Pdt where it
might be valid to use third party dependencies. But also here I'd ask
whether the maintainability will be increased. A totally different
question though is whether we actually need to maintain a special tool
for building the docs or whether we can use a pre-existing tool for
that. I am mainly thinking about either phpDocumentor or a default
docbook renderer. But that is a totally differnt topic IMO.

So I'd see this exactly the other way around:

usage for infra needs very careful consideration to not increase the
maintenance-burden on those that actually 'do' the maintenance.

Well, the RFC is not about that projects should use some tools or
libraries or frameworks, but rather that they can choose to do so if
they deem it valuable. Of course, the projects should not only look at
the short term benefit, but also on the long term maintenance burden.

This is the nut of it, really. The truth is that we are using and referring to third-party PHP projects within the websites and documentation as has been noted elsewhere in the thread. To say that this RFC should be a choice between what I have proposed and it's opposite is to potentially create a lot of work in ripping out those dependencies that have crept in over the years if we really want the policy to be the opposite.

By saying that the web and documentation projects "can use or document the existence of third-party PHP projects" it's not saying they will, but that the decision making about that will be returned to those actually working on those parts of the project and not subject to the current quasi-policy that "we don't do that except when we do".

If someone wants to contribute a chapter to the documentation that says "Here's what a framework is in PHP and here are a few examples of popular ones", the people writing and translating the documentation should hash that out. It shouldn't require an RFC, an argument on this list, and a vote among people who aren't writing and translating the documentation. (Especially because there are people whose sole or main contribution to the PHP project is that documentation work and not to php-src and they don't even get to vote!)

If someone wants to build an RFC tool for the project using some Composer libraries or even a framework, the people who have taken on the responsibility for maintaining the project websites and infrastructure should hash that out. It shouldn't require an RFC, an argument on this list, and a vote among people who aren't going to be working on it. (Especially because there are people whose sole or main contribution to the PHP project is to maintaining the websites and/or infrastructure and not to php-src and they don't even get to vote!)

Jim

3 months ago by Rob Landers — view source

unread

I see this a bid differently to be honest. While I understand that using
third party packages in our internal tools might make things easier in
the short term it will cause a lot or additional work in the long term.

Currently we have a lot of small scripts that do one thing. And they do
it for a long time with very little maintenance effort. Blowing these
scripts up with third-party libraries will mean that we will have to put
in much more maintenance effort for either keeping the dependencies up
to date or mostly rewriting the script the moment a change needs to
happen as the libraries will be outdated.

There are though some actual console applications like Pdt where it
might be valid to use third party dependencies. But also here I'd ask
whether the maintainability will be increased. A totally different
question though is whether we actually need to maintain a special tool
for building the docs or whether we can use a pre-existing tool for
that. I am mainly thinking about either phpDocumentor or a default
docbook renderer. But that is a totally differnt topic IMO.

So I'd see this exactly the other way around:

usage for infra needs very careful consideration to not increase the
maintenance-burden on those that actually 'do' the maintenance.

Well, the RFC is not about that projects should use some tools or
libraries or frameworks, but rather that they can choose to do so if
they deem it valuable. Of course, the projects should not only look at
the short term benefit, but also on the long term maintenance burden.

This is the nut of it, really. The truth is that we are using and referring to third-party PHP projects within the websites and documentation as has been noted elsewhere in the thread. To say that this RFC should be a choice between what I have proposed and it's opposite is to potentially create a lot of work in ripping out those dependencies that have crept in over the years if we really want the policy to be the opposite.

By saying that the web and documentation projects "can use or document the existence of third-party PHP projects" it's not saying they will, but that the decision making about that will be returned to those actually working on those parts of the project and not subject to the current quasi-policy that "we don't do that except when we do".

If someone wants to contribute a chapter to the documentation that says "Here's what a framework is in PHP and here are a few examples of popular ones", the people writing and translating the documentation should hash that out. It shouldn't require an RFC, an argument on this list, and a vote among people who aren't writing and translating the documentation. (Especially because there are people whose sole or main contribution to the PHP project is that documentation work and not to php-src and they don't even get to vote!)

If someone wants to build an RFC tool for the project using some Composer libraries or even a framework, the people who have taken on the responsibility for maintaining the project websites and infrastructure should hash that out. It shouldn't require an RFC, an argument on this list, and a vote among people who aren't going to be working on it. (Especially because there are people whose sole or main contribution to the PHP project is to maintaining the websites and/or infrastructure and not to php-src and they don't even get to vote!)

Jim

As far as RFC tools go, if you are more familiar with GitHub-flavored Markdown (gfmd) and find the RFC Markdown somewhat hard to use, I have https://github.com/bottledcode/RFC which you can fork and write an RFC draft in gfmd which it will convert to the wiki format. I find it much easier this way because I have other tooling dedicated to working with gfmd (layout previewers, synced editors between my phone/computer, grammar highlighting, etc).

It would be interesting to have this in the php-src org as a more accessible way to draft RFCs and have it synced to the wiki. That could also be a place for technical reviews (not feature reviews, which would continue to exist here).

— Rob

3 months ago by Deleu — view source

unread

I see this a bid differently to be honest. While I understand that using
third party packages in our internal tools might make things easier in
the short term it will cause a lot or additional work in the long term.

Currently we have a lot of small scripts that do one thing. And they do
it for a long time with very little maintenance effort. Blowing these
scripts up with third-party libraries will mean that we will have to put
in much more maintenance effort for either keeping the dependencies up
to date or mostly rewriting the script the moment a change needs to
happen as the libraries will be outdated.

There are though some actual console applications like Pdt where it
might be valid to use third party dependencies. But also here I'd ask
whether the maintainability will be increased. A totally different
question though is whether we actually need to maintain a special tool
for building the docs or whether we can use a pre-existing tool for
that. I am mainly thinking about either phpDocumentor or a default
docbook renderer. But that is a totally differnt topic IMO.

So I'd see this exactly the other way around:

usage for infra needs very careful consideration to not increase the
maintenance-burden on those that actually 'do' the maintenance.

I like the fact this has been brought up as it seems an equally important
consideration from my perspective. On one hand I remember reading about how
PHP Internals could hugely benefit from more volunteers to help maintain
the auxiliary projects of the language - which doesn't require C knowledge.
Perhaps this 'need' might be outdated now with the Foundation hiring
employees to work on PHP. On the other hand there's this really good point
about not creating a burden for existing maintainers of existing tools.
Ultimately, I find it important to consider that a tool that has been
"mostly no maintenance cost" for 10~20 years, then it might be following
PHP development practices so long gone that it's harder to capture new
volunteers. I understand there's a historical context in the 2000's where
PHP frameworks would come and go and most companies had their own in-house
framework. That reality is long-gone and community projects like Symfony,
Laravel and Composer are sustainable businesses that simultaneously rely on
PHP and make PHP better. Nowadays it is unlikely that a PHP developer will
pick up greenfield work with the language without using some reliable tool
provided by the community.

As it has been said, it is a disservice to the PHP project to be stuck on
vanilla PHP for things that require improvements, maintainers, revamp, etc.

--
Marco Deleu

3 months ago by Pere Orga — view source

unread

Missatge de Deleu deleugyn@gmail.com del dia dt., 27 d’ag. 2024 a les 13:55:

I see this a bid differently to be honest. While I understand that using
third party packages in our internal tools might make things easier in
the short term it will cause a lot or additional work in the long term.

Currently we have a lot of small scripts that do one thing. And they do
it for a long time with very little maintenance effort. Blowing these
scripts up with third-party libraries will mean that we will have to put
in much more maintenance effort for either keeping the dependencies up
to date or mostly rewriting the script the moment a change needs to
happen as the libraries will be outdated.

There are though some actual console applications like Pdt where it
might be valid to use third party dependencies. But also here I'd ask
whether the maintainability will be increased. A totally different
question though is whether we actually need to maintain a special tool
for building the docs or whether we can use a pre-existing tool for
that. I am mainly thinking about either phpDocumentor or a default
docbook renderer. But that is a totally differnt topic IMO.

So I'd see this exactly the other way around:

usage for infra needs very careful consideration to not increase the
maintenance-burden on those that actually 'do' the maintenance.

I like the fact this has been brought up as it seems an equally important consideration from my perspective. On one hand I remember reading about how PHP Internals could hugely benefit from more volunteers to help maintain the auxiliary projects of the language - which doesn't require C knowledge. Perhaps this 'need' might be outdated now with the Foundation hiring employees to work on PHP. On the other hand there's this really good point about not creating a burden for existing maintainers of existing tools. Ultimately, I find it important to consider that a tool that has been "mostly no maintenance cost" for 10~20 years, then it might be following PHP development practices so long gone that it's harder to capture new volunteers. I understand there's a historical context in the 2000's where PHP frameworks would come and go and most companies had their own in-house framework. That reality is long-gone and community projects like Symfony, Laravel and Composer are sustainable businesses that simultaneously rely on PHP and make PHP better. Nowadays it is unlikely that a PHP developer will pick up greenfield work with the language without using some reliable tool provided by the community.

As it has been said, it is a disservice to the PHP project to be stuck on vanilla PHP for things that require improvements, maintainers, revamp, etc.

It would be helpful if you could share examples of open-source,
long-term websites built using frameworks like Laravel, Symfony,
Laminas, CakePHP, or similar, especially those to which you have
contributed, ideally maintained by volunteers.

--
Pere Orga

3 months ago by Gina P. Banyard — view source

unread

I do in particular reject the notion that we should document third-party projects (usage for our infra is fine).

The point of the PHP documentation is to describe the PHP runtime and PECL extensions, which are both officially distributed through php.net.

Anything not related to these does not belong into the manual, much less into core documentation (like language/oop5 autoload.xml, to take the example from https://github.com/php/doc-en/pull/3677/files).

Changing this current unwritten rule is an invitation to implicitly promote specific projects. The question is really where does it end? Would we for example also mention PSRs as "widely followed guidelines for interoperability" or something? It's a strong invitation for some scope creep.

As such I strongly condemn the idea of inclusion of this guideline.

There are, ultimately, enough ways for people to learn about the PHP ecosystem, the php.net documentation is none of them. If I go to php.net, it's because I want to learn about the runtime, not its ecosystem.

As someone that has maintained the docs for a few years, there are a couple of misconceptions here.

We already promote some projects in favour of others, namely in the installation sections.
We promote some cloud vendors, but not all. [1]
We promote some installation methods, but not all, and when one project wrote docs to be included it has remained in limbo for 2 years. [2]

Moreover, we promote some conferences, but not others (and this is mainly due to if people figure out how to submit a PR on web-php).
We even have a calendar of meetups, which is all likely hood is severely out of date: https://www.php.net/cal.php

Moreover, PECL extensions are part of the PHP ecosystem and not the runtime, so why do some PECL extension have the right to live on the php.net website, but not others?
And frankly, I would prefer that we would get rid of PECL extension from the php.net documentation, as most of them are in a terrrible state with no way for us to easily improve on them, except that it is somehow the responsability of the doc team to do it.

As such the statement that the php.net website and it's documentation is not for people to learn about the PHP ecosystem seems blatently false.
Because it is, and has been for a very long time.

Thus, in my opinion, your current position is non-sensical.
Either the php.net website should not endorse any external project, which mean no mention of Apache, Cloud vendors, PECL extensions, NGNIX, XAMPP, WampServer, etc.
Or we continue to do this, and provide clear guidelines and procedures on how a project can be added onto the php.net documentation.

Composer is a de-facto standard of the PHP ecosystem, more than the V8js, Seaslog, or Recode PECL extensions.
The fact we don't even mention Composer, or another place where one can learn about the PHP ecosystem on the php.net website is frankly outrageous.

The Python.org website mentions Pypi, various IDEs, and even books that people can use to learn Python.
Heck, it even has a community Job board.
The go.dev mainpage even promotes companies that use Go.
Similarly rust-lang.org promotes companies that use Rust in production and IDEs that have first class support for writing Rust.
ruby-lang.org has a community tab, but even the documentation tab promotes external tutorials.
Similarly elixir-lang.org does the same and promotes companies, and books.
I'm pretty sure if I continue looking at the websites for various programming languages I can find more and more examples.

And the reson for this, is people new to the language don't know where to go looking and which resources are somewhat reasonable.
Having the php.net website point to various curated tutorials, industry standard packages and tools, seems fairly natural.
And not doing this clearly makes us an outlier rather than the norm.

This is not to say we should mention everything under the sun on the website, but this is where designing a process on how to decide on this comes into place.

Best regards,
Gina P. Banyard

[1] https://www.php.net/manual/en/install.cloud.php
[2] https://github.com/php/doc-en/pull/1674

3 months ago by Derick Rethans — view source

unread

Moreover, PECL extensions are part of the PHP ecosystem and not the
runtime, so why do some PECL extension have the right to live on the
php.net website, but not others?

They always were allowed to be on there. It is just that very few
third party PECL developers wanted to spend the time doing that,
consdiering Docbook isn't the easiest to use.

cheers,
Derick

3 months ago by Christoph M. Becker — view source

unread

We promote some installation methods, but not all, and when one project wrote docs to be included it has remained in limbo for 2 years. [2]

[2] https://github.com/php/doc-en/pull/1674

Well, that is about a freemium product, and we may want to
advertize/endorse OpenSource projects only. If the latter, we may want
to remove information about macOS, IIS, Windows etc. from the manual. ;)

Kidding aside: I'm not sure if we should add documentation for such
freemium products, since that may easily cause more of such PRs, and
where do we stop?

Christoph

3 months ago by Bilge — view source

unread

Hi,

Another RFC around process:
https://wiki.php.net/rfc/web-and-doc-use-not-endorsement

Feedback would be appreciated. My intention is to start voting on
September 9th unless there is still ongoing discussion.

Thanks.

Jim

It seems improbable to me that internals can flourish with
institutionalised NIH syndrome.

Cheers,
Bilge

2 months ago by Jim Winstead — view source

unread

Hi,

Another RFC around process: https://wiki.php.net/rfc/web-and-doc-use-not-endorsement

Feedback would be appreciated. My intention is to start voting on September 9th unless there is still ongoing discussion.

It has taken me longer than initially anticipated to circle back to this, but I intend to open the voting on this RFC on Thursday (2024-09-26T16:00:00Z or so) unless there are any other changes that anyone would like to propose.

The RFC again: https://wiki.php.net/rfc/web-and-doc-use-not-endorsement

Thanks.

Jim

2 months ago by tim@bastelstu.be — view source

unread

Am 2024-09-25 01:45, schrieb Jim Winstead:

It has taken me longer than initially anticipated to circle back to
this, but I intend to open the voting on this RFC on Thursday
(2024-09-26T16:00:00Z or so) unless there are any other changes that
anyone would like to propose.

The RFC again: https://wiki.php.net/rfc/web-and-doc-use-not-endorsement

Thank you. I've used your reminder as the opportunity to catch up with
this thread after my vacation.

I'm likely going to vote “no” on your RFC, because I do not believe that
your proposed statement of principle makes the situation any less
vague. It just makes the situation vague in a different way, because
there are no guidelines regarding what is acceptable and what is not, as
also mentioned by others in this RFC's discussion thread.

Best regards
Tim Düsterhus

2 months ago by Jim Winstead — view source

unread

Hi

Am 2024-09-25 01:45, schrieb Jim Winstead:

It has taken me longer than initially anticipated to circle back to
this, but I intend to open the voting on this RFC on Thursday
(2024-09-26T16:00:00Z or so) unless there are any other changes that
anyone would like to propose.

The RFC again: https://wiki.php.net/rfc/web-and-doc-use-not-endorsement

Thank you. I've used your reminder as the opportunity to catch up with
this thread after my vacation.

I'm likely going to vote “no” on your RFC, because I do not believe that
your proposed statement of principle makes the situation any less
vague. It just makes the situation vague in a different way, because
there are no guidelines regarding what is acceptable and what is not, as
also mentioned by others in this RFC's discussion thread.

I am very open to discussing guidelines that anyone thinks would be more acceptable than my proposal.

I think the closest anyone has come to another suggestion so far is Larry's proposal that individual deviations from the currently-unspecified policy should be settled by an RFC. (https://news-web.php.net/php.internals/125284)

The currently unstated guideline is "don't mention third-party tools" and it has been very inconsistently enforced so we have things like https://www.php.net/manual/en/install.windows.tools.php and https://www.php.net/manual/en/install.macosx.packages.php.

We have 250 pages of documentation for a UI extension that hasn't seen any movement in eight years (https://www.php.net/manual/en/book.ui.php), but the documentation can't mention Composer because it's the wrong sort of contribution to the PHP ecosystem.

Jim