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

Reply via email to