Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:125309
Date: Tue, 27 Aug 2024 12:34:28 +0100 (BST)
To: Deleu <deleugyn@gmail.com>
cc: Bob Weinand <bobwei9@hotmail.com>, Jim Winstead <jimw@trainedmonkey.com>, 
    internals@lists.php.net
Subject: Re: [PHP-DEV] [RFC] [Discussion] Using and Mentioning Third-party
 Packages in PHP Documentation and Web Projects
In-Reply-To: <CADK1yXKt0aAL1JNUZcZn9uR38_+82qj1Rz3rZNztfL-SdHFKnQ@mail.gmail.com>
Message-ID: <477e7b2f-8d76-7594-74c1-79bd96681b8a@php.net>
References: <642cb3ea-bf51-4832-8539-0540742000e1@app.fastmail.com> <AM8P250MB0170D0B5229EC7BA2D13609FE28B2@AM8P250MB0170.EURP250.PROD.OUTLOOK.COM> <CADK1yXKt0aAL1JNUZcZn9uR38_+82qj1Rz3rZNztfL-SdHFKnQ@mail.gmail.com>
Precedence: bulk
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="8323329-1617747547-1724758469=:23442"
From: derick@php.net (Derick Rethans)

  This message is in MIME format.  The first part should be readable text,
  while the remaining parts are likely unreadable without MIME-aware tools.

--8323329-1617747547-1724758469=:23442
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: QUOTED-PRINTABLE

On Mon, 26 Aug 2024, Deleu wrote:

> On Mon, Aug 26, 2024 at 3:12=E2=80=AFPM Bob Weinand <bobwei9@hotmail.com>=
 wrote:
>=20
> > Thanks for bringing this up - I also suggest that we make this a=20
> > binary choice - either we adopt the proposed language or its=20
> > opposite.
> >
> > I.e. a rejection of this should codify that statement in the=20
> > negative.
> >
> > I do in particular reject the notion that we should document=20
> > third-party projects (usage for our infra is fine).
> >
> > The point of the PHP documentation is to describe the PHP runtime=20
> > and PECL extensions, which are both officially distributed through=20
> > php.net.
> >
> > Anything not related to these does not belong into the manual, much=20
> > less into core documentation (like language/oop5 autoload.xml, to=20
> > take the example from=20
> > https://github.com/php/doc-en/pull/3677/files).
> >
> > Changing this current unwritten rule is an invitation to implicitly=20
> > promote specific projects. The question is really where does it end?=20
> > Would we for example also mention PSRs as "widely followed=20
> > guidelines for interoperability" or something? It's a strong=20
> > 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=20
> > ecosystem, the php.net documentation is none of them. If I go to=20
> > php.net, it's because I want to learn about the runtime, not its=20
> > ecosystem.
> >
> Since your message was somewhat ambiguous to me, I would like to take=20
> this opportunity to request clarification from Jim.
>=20
> I read this RFC as an opportunity to allow community-driven PHP=20
> projects to be embraced when it suits PHP's internals needs. For=20
> instance, I remember a few years ago a conversation about rebuilding=20
> the php.net website. The current "unwritten" rule was used to impose=20
> that a new PHP website could not use any existing PHP Framework as to=20
> not "endorse" any particular project. Same thing goes for the RFC=20
> Voting process, PSRs, Composer, etc.

I think there is a difference between "using existing packages to make=20
our life easier" and "we use this fully fledged framework". The latter=20
should still not be a reasonable outcome here.

> In a way, I agree with Bob's take that the php.net documentation=20
> should not be used to *document* 3rd-party tooling, but my=20
> interpretation of the RFC has nothing to do with documenting 3rd-party=20
> 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=20
Composer on php.net. That is ludicrous.

Documenting *proprietary* installers (such as AMPSS as raised in=20
https://github.com/php/doc-en/pull/1674) is probably something I *won't*=20
favour.

Explaining how to install PHP with homebrew, apt or yum makes perfect=20
sense to me. Nobody really ought to go to www.php.net/download and=20
compile PHP themselves. But that's the only installation instructions=20
that we have.

cheers,
Derick
--8323329-1617747547-1724758469=:23442--