Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:125284
Feedback-ID: i8414410d:Fastmail
Precedence: bulk
MIME-Version: 1.0
Date: Mon, 26 Aug 2024 13:26:28 -0500
To: "php internals" <internals@lists.php.net>
Message-ID: <450845aa-961a-4b03-9ae3-9a181e1e6405@app.fastmail.com>
In-Reply-To: 
 <AM8P250MB0170D0B5229EC7BA2D13609FE28B2@AM8P250MB0170.EURP250.PROD.OUTLOOK.COM>
References: <642cb3ea-bf51-4832-8539-0540742000e1@app.fastmail.com>
 <AM8P250MB0170D0B5229EC7BA2D13609FE28B2@AM8P250MB0170.EURP250.PROD.OUTLOOK.COM>
Subject: Re: [PHP-DEV] [RFC] [Discussion] Using and Mentioning Third-party Packages in
 PHP Documentation and Web Projects
Content-Type: text/plain
Content-Transfer-Encoding: 7bit
From: larry@garfieldtech.com ("Larry Garfield")

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: 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