Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:125303
Message-ID: <2c2f13b5-9cad-4bcc-b59f-01693e494bb3@heigl.org>
Date: Tue, 27 Aug 2024 07:03:10 +0200
Precedence: bulk
MIME-Version: 1.0
User-Agent: Mozilla Thunderbird
Subject: Re: [PHP-DEV] [RFC] [Discussion] Using and Mentioning Third-party
 Packages in PHP Documentation and Web Projects
To: internals@lists.php.net
References: <642cb3ea-bf51-4832-8539-0540742000e1@app.fastmail.com>
 <AM8P250MB0170D0B5229EC7BA2D13609FE28B2@AM8P250MB0170.EURP250.PROD.OUTLOOK.COM>
Autocrypt: addr=andreas@heigl.org; keydata=
 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
In-Reply-To: <AM8P250MB0170D0B5229EC7BA2D13609FE28B2@AM8P250MB0170.EURP250.PROD.OUTLOOK.COM>
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 8bit
From: andreas@heigl.org (Andreas Heigl)

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: 
>> 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                          |
+---------------------------------------------------------------------+