Re: Use PSR coding guidelines in php.net docs (instead of PEAR-CS)

pt., 4 wrz 2020 o 18:32 G. P. B. <[email protected]> napisał(a):

>
>>
> The PHP documentation doesn't endorse any coding style as the examples
> aren't very consistent, and I'd argue most of the examples follow PSR-2
> more or less.
> For the sake of argument, let's say PSR-2 is the current official
> coding-standard, should we still "upgrade" to PSR-12 although it is
> incompatible with PSR-2?
>

Its up to the maintainers to change the standard used. If they don't see
much benefit in following newer version of PSR, they can stay on the old
version. Or just copy the rules from PSR and state that these are rules to
follow when providing examples.


> If so, which tooling is available or need to be created such that:
>  - Coding style is enforced
>  - Automatic fixes, or pre-commit hooks which denies the commit
> Which works on the current PHP Documentation infrastructure (SVN) and can
> deal with Docbooks the format in which the PHP doc is written.
>

There are multiple tools which can enforce/validate coding style in PHP
world, and I'm sure that
it is possible to automatically migrate current code snippets to new style,
or to validate it in CI pipeline or pre commit.
I don't know the details of the current docs infrastructure, so I can't say
right now how to solve it in details, but I'm happy to help once there is a
decision to go this path.


> Moreover, those rather superficial changes put a lot of strain on
> translations because now a bunch of legit pages which need to be updated
> are buried under the tons of pages which need coding style updates. And
> automatic fixes and revision updates for translations is not something
> doable in the current state of affairs.
>

Any change which brings consistency requires work. Right now the code in
dosc is not even following the PEAR-CS, so a change would be needed anyway.


> And what happens if the FIG implodes on itself and another body creates a
> new coding style taking into account features which might only exist 5
> years from now? Should we then change again?
>

You don't have to follow any FIG standards if you don't want to. But I see
the benefit of having consistency in docs and having some rules to follow
there.
As I said, if you don't like to mention PSR by name, let's use the same
rules, and enforce them in docs.

To make further discussion more fruitful, let me ask a few questions:
1) do you see a value in having consistent examples in the docs?
2) do you see that it's not nice to require doc contributors to use
PEAR-CS, which is outdated and incomplete (and the whole pear is deprecated)
3) do you agree that using styles like PSR (even if we don't call it by
name) would be OK to use in docs examples?
4) do you see additional conditions which would need to be fulfilled to
approve such a change? e.g. having a CLI tool to validate/ fix styles

Best regards
Tymoteusz

>