The coding style for the documentation has been documented to be the PEAR coding standard (Manual :: Coding Standards) which is more than a little out-dated at this point. This has come up in at least a few PR reviews recently.
I don't think we should be aggressive about going in and updating existing examples, but should strive to make sure that new and changed examples are in sync with the new CS through reviews and perhaps automated checks.
(I guess the last time this came up it got bogged down in the quagmire about whether using a PHP-FIG standard implied some sort of favoritism or endorsement or whatever. Maybe we'll have to open a RFC on internals@ to address this documentation issue? php.doc: Use PSR coding guidelines in php.net docs (instead of PEAR-CS))
The coding style for the documentation has been documented to be the PEAR coding standard (Manual :: Coding Standards) which is more than a little out-dated at this point. This has come up in at least a few PR reviews recently.
I don't think we should be aggressive about going in and updating existing examples, but should strive to make sure that new and changed examples are in sync with the new CS through reviews and perhaps automated checks.
(I guess the last time this came up it got bogged down in the quagmire about whether using a PHP-FIG standard implied some sort of favoritism or endorsement or whatever. Maybe we'll have to open a RFC on internals@ to address this documentation issue? php.doc: Use PSR coding guidelines in php.net docs (instead of PEAR-CS))
On Mon, Oct 14, 2024, at 2:43 PM, Jim Winstead wrote:
The coding style for the documentation has been documented to be the
PEAR coding standard (Manual :: Coding Standards)
which is more than a little out-dated at this point. This has come up
in at least a few PR reviews recently.
I don't think we should be aggressive about going in and updating
existing examples, but should strive to make sure that new and changed
examples are in sync with the new CS through reviews and perhaps
automated checks.
(I guess the last time this came up it got bogged down in the quagmire
about whether using a PHP-FIG standard implied some sort of favoritism
or endorsement or whatever. Maybe we'll have to open a RFC on
internals@ to address this documentation issue? php.doc: Use PSR coding guidelines in php.net docs (instead of PEAR-CS))
Jim
I am unsurprisingly in favor of this. (Disclosure: I am currently the editor for PER-CS. Expect a 2.1 release out by EOY, hopefully.)
On Mon, Oct 14, 2024, at 12:43 PM, Jim Winstead wrote:
The coding style for the documentation has been documented to be the
PEAR coding standard (Manual :: Coding Standards)
which is more than a little out-dated at this point. This has come up
in at least a few PR reviews recently.
I don't think we should be aggressive about going in and updating
existing examples, but should strive to make sure that new and changed
examples are in sync with the new CS through reviews and perhaps
automated checks.
(I guess the last time this came up it got bogged down in the quagmire
about whether using a PHP-FIG standard implied some sort of favoritism
or endorsement or whatever. Maybe we'll have to open a RFC on
internals@ to address this documentation issue? php.doc: Use PSR coding guidelines in php.net docs (instead of PEAR-CS))
Here is a PR implementing this change against the updated contribution guide that will be live on doc.php.net soon.
In a different PR to update a bit about grammar in the style guidelines, I added some text about how these style guidelines are supposed to be applied:
tl;dr Guidelines apply to new docs and docs being revised where it won't overly burden translators.