Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:125332
Feedback-ID: ia2404087:Fastmail
Precedence: bulk
MIME-Version: 1.0
Date: Tue, 27 Aug 2024 18:46:28 -0700
To: internals@lists.php.net
Message-ID: <aeeaa783-cc5e-4c2e-9e1a-9575428ed48e@app.fastmail.com>
In-Reply-To: <383252f6-d0e8-4f29-8f01-a71e5ed26d90@gmx.de>
References: <642cb3ea-bf51-4832-8539-0540742000e1@app.fastmail.com>
 <AM8P250MB0170D0B5229EC7BA2D13609FE28B2@AM8P250MB0170.EURP250.PROD.OUTLOOK.COM>
 <2c2f13b5-9cad-4bcc-b59f-01693e494bb3@heigl.org>
 <383252f6-d0e8-4f29-8f01-a71e5ed26d90@gmx.de>
Subject: Re: [PHP-DEV] [RFC] [Discussion] Using and Mentioning Third-partyPackages in
 PHP Documentation and Web Projects
Content-Type: text/plain
Content-Transfer-Encoding: 7bit
From: jimw@trainedmonkey.com ("Jim Winstead")

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