Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:125333
Feedback-ID: ifab94697:Fastmail
Precedence: bulk
MIME-Version: 1.0
Date: Wed, 28 Aug 2024 09:05:12 +0200
To: internals@lists.php.net
Message-ID: <32587523-6c86-4100-9a65-4d9282baafde@app.fastmail.com>
In-Reply-To: <aeeaa783-cc5e-4c2e-9e1a-9575428ed48e@app.fastmail.com>
References: <642cb3ea-bf51-4832-8539-0540742000e1@app.fastmail.com>
 <AM8P250MB0170D0B5229EC7BA2D13609FE28B2@AM8P250MB0170.EURP250.PROD.OUTLOOK.COM>
 <2c2f13b5-9cad-4bcc-b59f-01693e494bb3@heigl.org>
 <383252f6-d0e8-4f29-8f01-a71e5ed26d90@gmx.de>
 <aeeaa783-cc5e-4c2e-9e1a-9575428ed48e@app.fastmail.com>
Subject: Re: [PHP-DEV] [RFC] [Discussion] Using and Mentioning Third-partyPackages in
 PHP Documentation and Web Projects
Content-Type: multipart/alternative;
 boundary=707b80f2795847e6b7d7ec35fc8bf405
From: rob@bottled.codes ("Rob Landers")

--707b80f2795847e6b7d7ec35fc8bf405
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: quoted-printable



On Wed, Aug 28, 2024, at 03:46, Jim Winstead wrote:
> On Tue, Aug 27, 2024, at 4:46 AM, Christoph M. Becker wrote:
> > On 27.08.2024 at 07:03, Andreas Heigl wrote:
> >
> >> 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 t=
erm.
> >>
> >> Currently we have a lot of small scripts that do one thing. And the=
y do
> >> it for a long time with very little maintenance effort. Blowing the=
se
> >> scripts up with third-party libraries will mean that we will have t=
o 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 a=
sk
> >> whether the maintainability will be increased. A totally different
> >> question though is whether we actually need to maintain a special t=
ool
> >> 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.
> >
> > Well, the RFC is not about that projects *should* use some tools or
> > libraries or frameworks, but rather that they *can* choose to do so =
if
> > they deem it valuable.  Of course, the projects should not only look=
 at
> > the short term benefit, but also on the long term maintenance burden.
>=20
> This is the nut of it, really. The truth is that we are using and refe=
rring to third-party PHP projects within the websites and documentation =
as has been noted elsewhere in the thread. To say that this RFC should b=
e a choice between what I have proposed and it's opposite is to potentia=
lly create a lot of work in ripping out those dependencies that have cre=
pt in over the years if we really want the policy to be the opposite.
>=20
> By saying that the web and documentation projects "can use or document=
 the existence of third-party PHP projects" it's not saying they will, b=
ut that the decision making about that will be returned to those actuall=
y working on those parts of the project and not subject to the current q=
uasi-policy that "we don't do that except when we do".
>=20
> If someone wants to contribute a chapter to the documentation that say=
s "Here's what a framework is in PHP and here are a few examples of popu=
lar ones", the people writing and translating the documentation should h=
ash that out. It shouldn't require an RFC, an argument on this list, and=
 a vote among people who aren't writing and translating the documentatio=
n. (Especially because there are people whose sole or main contribution =
to the PHP project is that documentation work and not to php-src and the=
y don't even get to vote!)
>=20
> If someone wants to build an RFC tool for the project using some Compo=
ser libraries or even a framework, the people who have taken on the resp=
onsibility for maintaining the project websites and infrastructure shoul=
d hash that out. It shouldn't require an RFC, an argument on this list, =
and a vote among people who aren't going to be working on it. (Especiall=
y because there are people whose sole or main contribution to the PHP pr=
oject is to maintaining the websites and/or infrastructure and not to ph=
p-src and they don't even get to vote!)
>=20
> Jim
>=20

As far as RFC tools go, if you are more familiar with GitHub-flavored Ma=
rkdown (gfmd) and find the RFC Markdown somewhat hard to use, I have htt=
ps://github.com/bottledcode/RFC which you can fork and write an RFC draf=
t in gfmd which it will convert to the wiki format. I find it much easie=
r this way because I have other tooling dedicated to working with gfmd (=
layout previewers, synced editors between my phone/computer, grammar hig=
hlighting, etc).

It would be interesting to have this in the php-src org as a more access=
ible way to draft RFCs and have it synced to the wiki. That could also b=
e a place for technical reviews (not feature reviews, which would contin=
ue to exist here).

=E2=80=94 Rob
--707b80f2795847e6b7d7ec35fc8bf405
Content-Type: text/html; charset=utf-8
Content-Transfer-Encoding: quoted-printable

<!DOCTYPE html><html><head><title></title><style type=3D"text/css">p.Mso=
Normal,p.MsoNoSpacing{margin:0}=0Ap.MsoNormal,p.MsoNoSpacing{margin:0}</=
style></head><body><div><br></div><div><br></div><div>On Wed, Aug 28, 20=
24, at 03:46, Jim Winstead wrote:<br></div><blockquote type=3D"cite" id=3D=
"qt" style=3D""><div>On Tue, Aug 27, 2024, at 4:46 AM, Christoph M. Beck=
er wrote:<br></div><div>&gt; On 27.08.2024 at 07:03, Andreas Heigl wrote=
:<br></div><div>&gt;<br></div><div>&gt;&gt; I see this a bid differently=
 to be honest. While I understand that using<br></div><div>&gt;&gt; thir=
d party packages in our internal tools might make things easier in<br></=
div><div>&gt;&gt; the short term it will cause a lot or additional work =
in the long term.<br></div><div>&gt;&gt;<br></div><div>&gt;&gt; Currentl=
y we have a lot of small scripts that do one thing. And they do<br></div=
><div>&gt;&gt; it for a long time with very little maintenance effort. B=
lowing these<br></div><div>&gt;&gt; scripts up with third-party librarie=
s will mean that we will have to put<br></div><div>&gt;&gt; in much more=
 maintenance effort for either keeping the dependencies up<br></div><div=
>&gt;&gt; to date or mostly rewriting the script the moment a change nee=
ds to<br></div><div>&gt;&gt; happen as the libraries will be outdated.<b=
r></div><div>&gt;&gt;<br></div><div>&gt;&gt; There are though some actua=
l console applications like Pdt where it<br></div><div>&gt;&gt; might be=
 valid to use third party dependencies. But also here I'd ask<br></div><=
div>&gt;&gt; whether the maintainability will be increased. A totally di=
fferent<br></div><div>&gt;&gt; question though is whether we actually ne=
ed to maintain a special tool<br></div><div>&gt;&gt; for building the do=
cs or whether we can use a pre-existing tool for<br></div><div>&gt;&gt; =
that. I am mainly thinking about either phpDocumentor or a default<br></=
div><div>&gt;&gt; docbook renderer. But that is a totally differnt topic=
 IMO.<br></div><div>&gt;&gt;<br></div><div>&gt;&gt; So I'd see this exac=
tly the other way around:<br></div><div>&gt;&gt;<br></div><div>&gt;&gt; =
usage for infra needs very careful consideration to not increase the<br>=
</div><div>&gt;&gt; maintenance-burden on those that actually 'do' the m=
aintenance.<br></div><div>&gt;<br></div><div>&gt; Well, the RFC is not a=
bout that projects *should* use some tools or<br></div><div>&gt; librari=
es or frameworks, but rather that they *can* choose to do so if<br></div=
><div>&gt; they deem it valuable.&nbsp; Of course, the projects should n=
ot only look at<br></div><div>&gt; the short term benefit, but also on t=
he long term maintenance burden.<br></div><div><br></div><div>This is th=
e nut of it, really. The truth is that we are using and referring to thi=
rd-party PHP projects within the websites and documentation as has been =
noted elsewhere in the thread. To say that this RFC should be a choice b=
etween what I have proposed and it's opposite is to potentially create a=
 lot of work in ripping out those dependencies that have crept in over t=
he years if we really want the policy to be the opposite.<br></div><div>=
<br></div><div>By saying that the web and documentation projects "can us=
e or document the existence of third-party PHP projects" it's not saying=
 they will, but that the decision making about that will be returned to =
those actually working on those parts of the project and not subject to =
the current quasi-policy that "we don't do that except when we do".<br><=
/div><div><br></div><div>If someone wants to contribute a chapter to the=
 documentation that says "Here's what a framework is in PHP and here are=
 a few examples of popular ones", the people writing and translating the=
 documentation should hash that out. It shouldn't require an RFC, an arg=
ument on this list, and a vote among people who aren't writing and trans=
lating the documentation. (Especially because there are people whose sol=
e or main contribution to the PHP project is that documentation work and=
 not to php-src and they don't even get to vote!)<br></div><div><br></di=
v><div>If someone wants to build an RFC tool for the project using some =
Composer libraries or even a framework, the people who have taken on the=
 responsibility for maintaining the project websites and infrastructure =
should hash that out. It shouldn't require an RFC, an argument on this l=
ist, and a vote among people who aren't going to be working on it. (Espe=
cially because there are people whose sole or main contribution to the P=
HP project is to maintaining the websites and/or infrastructure and not =
to php-src and they don't even get to vote!)<br></div><div><br></div><di=
v>Jim<br></div><div><br></div></blockquote><div><br></div><div>As far as=
 RFC tools go, if you are more familiar with GitHub-flavored Markdown (g=
fmd) and find the RFC Markdown somewhat hard to use, I have&nbsp;<a href=
=3D"https://github.com/bottledcode/RFC">https://github.com/bottledcode/R=
FC</a>&nbsp;which you can fork and write an RFC draft in gfmd which it w=
ill convert to the wiki format. I find it much easier this way because I=
 have other tooling dedicated to working with gfmd (layout previewers, s=
ynced editors between my phone/computer, grammar highlighting, etc).<br>=
</div><div><br></div><div>It would be interesting to have this in the ph=
p-src org as a more accessible way to draft RFCs and have it synced to t=
he wiki. That could also be a place for technical reviews (not feature r=
eviews, which would continue to exist here).</div><div><br></div><div id=
=3D"sig121229152">=E2=80=94 Rob<br></div></body></html>
--707b80f2795847e6b7d7ec35fc8bf405--