Hey all
Am 26.08.24 um 20:06 schrieb Bob Weinand:
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).
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.
But mentioning - and encouraging - best practices for developing
PHP-Applications is something that the PHP-Project should actively provide.
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.
If I go to PHP.net, I want to learn about PHP. As an end user I don't
really care whether it's the runtime internals or the ecosystem. It is a
manual for PHP. And as such it should provide me with what we consider
Best Practices.
My 0.02€ from having done some maintenance on php.net.
Cheers
Andreas
--
,,,
(o o)
+---------------------------------------------------------ooO-(_)-Ooo-+
| Andreas Heigl |
| mailto:andr...@heigl.org N 50°22'59.5" E 08°23'58" |
| https://andreas.heigl.org |
+---------------------------------------------------------------------+
| https://hei.gl/appointmentwithandreas |
+---------------------------------------------------------------------+
| GPG-Key: https://hei.gl/keyandreasheiglorg |
+---------------------------------------------------------------------+
