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

On Wed, 9 Sep 2020 at 15:11, Tymoteusz Motylewski <[email protected]>
wrote:

>
>
> 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?
>

In general, yes.  That's why there are declared coding standards.  I'm
going to add here, if examples are not adhering to the declared rules or
guidelines (just like any other part of the documentation) then it is a bug
that should be fixed.


> 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)
>

It's just a coding standard. On "not nice", the PEAR coding standards are
not a cruel and unusual form of punishment. Besides, if it doesn't cover
everything that we want to standardise, we can add new rules. If its rules
are unacceptable, we can choose or define another set of standards. None of
this is written in stone.



> 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?
>

If the shoe fits.


> 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
>

A volunteer, or group of volunteers, to make it happen would be a
prerequisite to any serious discussion on the topic.  The pool of active
documentation contributors is absolutely tiny and I can't think of one
person in that group who would *want* to take this on; it will take someone
who really, really wants to scratch this particular itch to actually get it
done.


>
> Best regards
> Tymoteusz
>
>>