Re: [RFC] [Discussion] Using and Mentioning Third-partyPackages in PHP Documentation and Web Projects

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 term. > >> > >> Currently we have a lot of small scripts that do one thing. And they do > >> it for a long time with very little maintenance effort. Blowing these > >> scripts up with third-party libraries will mean that we will have to 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 ask > >> whether the maintainability will be increased. A totally different > >> question though is whether we actually need to maintain a special tool > >> 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. > > This is the nut of it, really. The truth is that we are using and referring to third-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 between 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 the years > if we really want the policy to be the opposite. > > 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, 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". > > 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 argument on > this list, and a vote among people who aren't writing and translating the documentation. > (Especially because there are people whose sole or main contribution to the PHP project is that > documentation work and not to php-src and they don't even get to vote!) > > 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 list, and > a vote among people who aren't going to be working on it. (Especially because there are people > whose sole or main contribution to the PHP project is to maintaining the websites and/or > infrastructure and not to php-src and they don't even get to vote!) > > Jim > As far as RFC tools go, if you are more familiar with GitHub-flavored Markdown (gfmd) and find the RFC Markdown somewhat hard to use, I have https://github.com/bottledcode/RFC which you can fork and write an RFC draft in gfmd which it will convert to the wiki format. I find it much easier this way because I have other tooling dedicated to working with gfmd (layout previewers, synced editors between my phone/computer, grammar highlighting, etc). It would be interesting to have this in the php-src org as a more accessible way to draft RFCs and have it synced to the wiki. That could also be a place for technical reviews (not feature reviews, which would continue to exist here). — Rob