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
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:
···
Marco Deleu
Hey Jim,
···
On 26.8.2024 19:44:18, Jim Winstead wrote:
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
On Mon, Aug 26, 2024, at 1:06 PM, Bob Weinand wrote:
Hey Jim,
On 26.8.2024 19:44:18, Jim Winstead wrote:
Hi,
Another RFC around process: PHP: 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 Add information about Composer and example of using it's autoloader by jimwins · Pull Request #3677 · php/doc-en · GitHub).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
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
On 26/08/2024 18:44, Jim Winstead wrote:
Hi,
Another RFC around process: PHP: 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
On Mon, 26 Aug 2024, Bob Weinand wrote:
On 26.8.2024 19:44:18, Jim Winstead wrote:
>
> Another RFC around process:
> PHP: 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 Add information about Composer and example of using it's autoloader by jimwins · Pull Request #3677 · php/doc-en · GitHub).
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
Hey all
Am 26.08.24 um 20:06 schrieb Bob Weinand:
Hey Jim,
On 26.8.2024 19:44:18, Jim Winstead wrote:
Hi,
Another RFC around process: PHP: 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 Add information about Composer and example of using it's autoloader by jimwins · Pull Request #3677 · php/doc-en · GitHub).
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 |
+---------------------------------------------------------------------+
| Appointments - Nextcloud |
+---------------------------------------------------------------------+
| GPG-Key: https://hei.gl/keyandreasheiglorg |
+---------------------------------------------------------------------+
On Monday, 26 August 2024 at 20:06, Bob Weinand <bobwei9@hotmail.com> wrote:
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 Add information about Composer and example of using it's autoloader by jimwins · Pull Request #3677 · php/doc-en · GitHub).
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: PHP: Events: August 2024
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] PHP: Installation on Cloud Computing platforms - Manual
[2] Adding AMPPS PHP installer by brijeshk89 · Pull Request #1674 · php/doc-en · GitHub
On Mon, 26 Aug 2024, Deleu wrote:
On Mon, Aug 26, 2024 at 3:12 PM Bob Weinand <bobwei9@hotmail.com> wrote:
> 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
> Add information about Composer and example of using it's autoloader by jimwins · Pull Request #3677 · php/doc-en · GitHub).
>
> 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
Adding AMPPS PHP installer by brijeshk89 · Pull Request #1674 · php/doc-en · GitHub) 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
On Tue, 27 Aug 2024, Gina P. Banyard wrote:
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
On 27.08.2024 at 07:03, Andreas Heigl wrote:
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
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
On 27.08.2024 at 12:37, Gina P. Banyard wrote:
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] Adding AMPPS PHP installer by brijeshk89 · Pull Request #1674 · php/doc-en · GitHub
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
Hey Christoph, hey all.
Am 27.08.24 um 13:46 schrieb Christoph M. Becker:
On 27.08.2024 at 07:03, Andreas Heigl wrote:
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 |
+---------------------------------------------------------------------+
| Appointments - Nextcloud |
+---------------------------------------------------------------------+
| GPG-Key: https://hei.gl/keyandreasheiglorg |
+---------------------------------------------------------------------+
On 27.08.2024 at 13:34, Derick Rethans wrote:
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
Missatge de Deleu <deleugyn@gmail.com> del dia dt., 27 d’ag. 2024 a les 13:55:
On Tue, Aug 27, 2024 at 2:06 AM Andreas Heigl <andreas@heigl.org> wrote:
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
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.
On Tue, Aug 27, 2024, at 4:46 AM, Christoph M. Becker wrote:
On 27.08.2024 at 07:03, Andreas Heigl wrote:
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
On Wed, Aug 28, 2024, at 03:46, Jim Winstead wrote:
On Tue, Aug 27, 2024, at 4:46 AM, Christoph M. Becker wrote:
On 27.08.2024 at 07:03, Andreas Heigl wrote:
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