Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:125290
Precedence: bulk
MIME-Version: 1.0
References: <642cb3ea-bf51-4832-8539-0540742000e1@app.fastmail.com> <AM8P250MB0170D0B5229EC7BA2D13609FE28B2@AM8P250MB0170.EURP250.PROD.OUTLOOK.COM>
In-Reply-To: <AM8P250MB0170D0B5229EC7BA2D13609FE28B2@AM8P250MB0170.EURP250.PROD.OUTLOOK.COM>
Date: Mon, 26 Aug 2024 17:05:53 -0300
Message-ID: <CADK1yXKt0aAL1JNUZcZn9uR38_+82qj1Rz3rZNztfL-SdHFKnQ@mail.gmail.com>
Subject: Re: [PHP-DEV] [RFC] [Discussion] Using and Mentioning Third-party
 Packages in PHP Documentation and Web Projects
To: Bob Weinand <bobwei9@hotmail.com>
Cc: Jim Winstead <jimw@trainedmonkey.com>, internals@lists.php.net
Content-Type: multipart/alternative; boundary="0000000000002158d806209ba988"
From: deleugyn@gmail.com (Deleu)

--0000000000002158d806209ba988
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

On Mon, Aug 26, 2024 at 3:12=E2=80=AFPM Bob Weinand <bobwei9@hotmail.com> w=
rote:

> 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 PEC=
L
> 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? Woul=
d
> 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.
>
>
> Bob
>
Since your message was somewhat ambiguous to me, I would like to take this
opportunity to request clarification from Jim.

I read this RFC as an opportunity to allow community-driven PHP projects to
be embraced when it suits PHP's internals needs. For instance, I remember a
few years ago a conversation about rebuilding the php.net website. The
current "unwritten" rule was used to impose that a new PHP website could
not use any existing PHP Framework as to not "endorse" any particular
project. Same thing goes for the RFC Voting process, PSRs, Composer, etc.

In a way, I agree with Bob's take that the php.net documentation should not
be used to *document* 3rd-party tooling, but my interpretation of the RFC
has nothing to do with documenting 3rd-party tools but instead its about
mentioning or even relying on them.

Current discussion about Generics going on talks a lot about phpstan and
psalm and whatever comes out of the work put into Generics, I would
definitely be in favour of PHP docs mentioning how Generics is already
present today with those tools. Current work-in-progress from the
Foundation in regards to revamping pecl involves (as far as I know)
providing PHP Extensions via Composer which would be something that said
"unwritten" rule could be mentioned for opposing such approach. There's
also PHP community members that would be willing to work on a new RFC
automation tool to improve on the process that has recently been mentioned
as "suboptimal" [1]. Such community members would certainly opt to build
this upon Symfony, Laravel, Slim or anything more convenient than vanilla
PHP and such "unwritten" rule keeps us chained to suboptimal infrastructure=
.

[1] https://externals.io/message/124843#124860


--=20
Marco Deleu

--0000000000002158d806209ba988
Content-Type: text/html; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

<div dir=3D"ltr"><div dir=3D"ltr"><br></div><br><div class=3D"gmail_quote">=
<div dir=3D"ltr" class=3D"gmail_attr">On Mon, Aug 26, 2024 at 3:12=E2=80=AF=
PM Bob Weinand &lt;<a href=3D"mailto:bobwei9@hotmail.com">bobwei9@hotmail.c=
om</a>&gt; wrote:<br></div><blockquote class=3D"gmail_quote" style=3D"margi=
n:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex=
"><u></u>

 =20
  <div>
    <p>Thanks for bringing this up - I also suggest that we make this a
      binary choice - either we adopt the proposed language or its
      opposite.<br></p>
    <p>I.e. a rejection of this should codify that statement in the
      negative.</p>
    <p>I do in particular reject the notion that we should document
      third-party projects (usage for our infra is fine).<br></p>
    <p>The point of the PHP documentation is to describe the PHP runtime
      and PECL extensions, which are both officially distributed through
      <a href=3D"http://php.net" target=3D"_blank">php.net</a>.</p>
    <p>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
      <a href=3D"https://github.com/php/doc-en/pull/3677/files" target=3D"_=
blank">https://github.com/php/doc-en/pull/3677/files</a>).</p>
    <p>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 &quot;widely
      followed guidelines for interoperability&quot; or something? It&#39;s=
 a
      strong invitation for some scope creep.<br></p>
    <p>As such I strongly condemn the idea of inclusion of this
      guideline.</p>
    <p>There are, ultimately, enough ways for people to learn about the
      PHP ecosystem, the <a href=3D"http://php.net" target=3D"_blank">php.n=
et</a> documentation is none of them. If I go
      to <a href=3D"http://php.net" target=3D"_blank">php.net</a>, it&#39;s=
 because I want to learn about the runtime, not
      its ecosystem.<br></p>
    <p><br>
    </p>
    <p>Bob<br>
    </p>
  </div>

</blockquote></div><div><div>Since your message was somewhat ambiguous to m=
e, I would like to take this opportunity to request clarification from Jim.=
</div><div><br></div><div>I read this RFC as an opportunity to allow commun=
ity-driven PHP projects to be embraced when it suits PHP&#39;s internals ne=
eds. For instance, I remember a few years ago a conversation about rebuildi=
ng the <a href=3D"http://php.net">php.net</a> website. The current &quot;un=
written&quot; rule was used to impose that a new PHP website could not use =
any existing PHP Framework as to not &quot;endorse&quot; any particular pro=
ject. Same thing goes for the RFC Voting process, PSRs, Composer, etc.</div=
><div><br></div><div>In a way, I agree with Bob&#39;s take that the <a href=
=3D"http://php.net">php.net</a> documentation should not be used to *docume=
nt* 3rd-party tooling, but my interpretation of the RFC has nothing to do w=
ith documenting 3rd-party tools but instead its about mentioning or even re=
lying on them.</div><div><br></div><div>Current discussion about Generics g=
oing on talks a lot about phpstan and psalm and whatever comes out of the w=
ork put into Generics, I would definitely be in favour of PHP docs mentioni=
ng how Generics is already present today with those tools. Current work-in-=
progress from the Foundation in regards to revamping pecl involves (as far =
as I know) providing PHP Extensions via Composer which would be something t=
hat said &quot;unwritten&quot; rule could be mentioned for opposing such ap=
proach. There&#39;s also PHP community members that would be willing to wor=
k on a new RFC automation tool to improve on the process that has recently =
been mentioned as &quot;suboptimal&quot; [1]. Such community members would =
certainly opt to build this upon Symfony, Laravel, Slim or anything more co=
nvenient than vanilla PHP and such &quot;unwritten&quot; rule keeps us chai=
ned to suboptimal infrastructure.</div><div><br></div><div>[1]=C2=A0<a href=
=3D"https://externals.io/message/124843#124860">https://externals.io/messag=
e/124843#124860</a></div><div><br></div><div><br></div><span class=3D"gmail=
_signature_prefix">-- </span><br><div dir=3D"ltr" class=3D"gmail_signature"=
><div dir=3D"ltr"><div dir=3D"ltr"><div dir=3D"ltr"><div dir=3D"ltr"><div d=
ir=3D"ltr"><div dir=3D"ltr"><div dir=3D"ltr">Marco Deleu</div></div></div><=
/div></div></div></div></div></div></div>

--0000000000002158d806209ba988--