PSR-PER 2.0.0 has been released

jrfnl commented 10 months ago

Repost from https://github.com/squizlabs/PHP_CodeSniffer/issues/3793:

PSR-PER is an evolving standard which builds onto PSR-12.

The first "release" (= updated standards publication) since the fork of PSR-12 has just been published.

I'm opening this ticket to allow for a discussion on if and if so, how to handle these evolving standards in PHPCS.

Refs:

https://github.com/php-fig/per-coding-style/releases/tag/2.0.0

https://github.com/php-fig/per-coding-style/compare/1.0.0...2.0.0

https://github.com/php-fig/per-coding-style/blob/2.0.0/spec.md

https://github.com/php-fig/per-coding-style/blob/2.0.0/meta.md

@kenguest asked:

Is there anything that can be done to help nudge this along?

Also, can I just note that the PER for Coding Standards shouldn't be referred to as a PSR - it is PER CS 2.0 :-)

I replied:

@kenguest Well, aside from the decision which still needs to be taken about this, it might be good to create an action list of the differences between PSR-12 and PSR-PER ?

For each difference, it will need to be determined whether there is an existing sniff which could handle this (possibly with a public property setting) or whether a new sniff is needed.

Another thing to have a good think about would be how to handle versioning, as without some form of versioning, a PSR-PER ruleset would be a moving target which could randomly start failing CI builds due to new rules being introduced (and being sniffed for).

@kenguest replied:

@jrfnl I'm working on a list of changes between the two standards, then an action list. PER-CS is at version 2 at the moment, and there will be distinct version numbers so it should just be a case of having one set of sniffs called PERCS200 (for v2.0.0) and so on.

My current line of thinking on this is as follows:

I agree with @kenguest that each PER version should have its own ruleset, like PER-200, to prevent it from becoming a moving target failing builds at random. Each ruleset can include the previous version and build on top of that.
For those repos who always want to use the latest version, there should also be a PER-latest, which would include the ruleset for the current version and would need to be updated each time a new version is added.
As there could be a lot of PER versions, adding these rulesets to the main PHPCS repo may be a bit unwieldy, so I'm thinking a separate repo in this organisation called PSR-PER.
Sniffs needed in the PER rulesets should still be pulled to the main PHPCS repo. The PSR-PER repo would only contain rulesets, not sniffs.

jazzsequence commented 7 months ago

Semantic point but I would second @kenguest's suggestion of naming and referring to the repo and standard as PER-CS (or a variation thereof) rather than PSR-PER. PSR specifically refers to PHP Standards Recommendations whereas PER refers to PHP Evolving Recommendations; combining the two feels like mixing separate interests (even as PER is an extension of PSR-12).

kenguest commented 3 months ago

Gentle reminder, @jrfnl, that there is a migration document detailing the differences between PSR-12 and PER-CS v2 at https://github.com/php-fig/per-coding-style/blob/master/migration-2.0.md should it need to be consulted for supporting PER-CS in PHP CodeSniffer.

This link hadn't been copied over from the squizlabs/phpcs ticket that I filed over a year ago.

jrfnl commented 3 months ago

This link hadn't been copied over from the squizlabs/phpcs ticket that I filed over a year ago.

@kenguest Yes, that comment was posted in the gap between when I opened this issue and the official take-over announcement, which is why it wasn't copied over.

I'd actually been thinking off this issue not too long ago.

If it wasn't clear from the above, my preference would be for this new repo to be run by a team of ~two maintainers, with me available in the background for consultation when needed.

The "vacancy" description for these roles would be as follows:

Tasks:

Initial set up of the PER-CS repo

Set up the initial PER 1.0.0, PER 2.0.0, PER-latest rulesets.
Find sniffs for those rules which were added/changed in PER 2.0.0 compared to PER 1.0.0 (PSR-12). The migration guide @kenguest linked to should be used as a basis for this.
Identify if there are rules which cannot be covered via the currently available sniffs and if so, open a feature request in this repo for each uncovered rule with a clear description of the specifications for the sniff which would need to be written. Where needed, ask for clarification from the PER team if there is any ambiguity as a sniff needs exact specifications to follow.
Set up CI/QA checks for the rulesets.
Register the package with Packagist.
Tag the initial release.

Continued maintenance of the PER-CS repo

Follow/watch this repo, in particular the PER related feature request tickets and new releases, to know when new sniffs are available which could fill in the gaps.
When "missing" sniffs become available, make the appropriate updates to the repo and tag a new release.
Follow/watch the php-fig/per-coding-style repo. Carefully scrutinize change proposals for ambiguity and ask for clarification where needed.
When a new PER release gets tagged, follow the recipe above (add a new ruleset, add the new ruleset to CI in all the appropriate places, find sniffs to add to it to cover the difference with the previous version, identify missing sniffs and open feature requests for those).

Optional additional tasks (time and skills permitting)

Verify that the sniffs used in the PER rulesets all have documentation and contribute to adding documentation if any is missing (also see #148)
Potentially volunteer to be part of the PER team ?
Potentially address the opened feature requests via PRs.
Potentially address gaps in the PER rules, like when new syntaxes get introduced in PHP, and open issues in the PER repo with standards suggestions/the suggestion to add rules for the new PHP syntaxes.

Time investment

For the initial setup, I'd estimate approximately a week's work. For the continued maintenance, I'd estimate 1 - 2 hours a month. For the optional tasks... I don't dare to put an estimate on that.

Planning

The call for volunteers for the above is open.

If anyone is interested, but wants help getting started, I'm happy to plan a few pairing sessions via videocall to help with the initial setup.

If there are several people who are potentially interested, but not yet sure if they are up for it, I'd be open to a mob programming session to help people get more familiar with the moving parts/answer any questions/explain whatever needs explaining.

Call to action

Anyone who is interested in getting involved with this, please, please leave a comment on this ticket.

stankarp commented 1 month ago

@jrfnl Any update on this issue? Have you managed to setup a new PER-CS repo or find someone who willing to volunteer?

jrfnl commented 1 month ago

@stankarp If there had been volunteers, you would have seen their comments in this ticket (or a comment by me that people had reached out privately), so no progress so far, unfortunately.

My offer to help get this off the ground with some videocalls to get the maintainers started is still open.

rikvdh commented 1 month ago

@jrfnl I'm considering supporting this. I do not have loads of spare time, but I would love to work on this. According to your 'to do' list above, my first question would be. Is this desirable in a separate repo, or integrated into this repo?

jrfnl commented 1 month ago

@jrfnl I'm considering supporting this. I do not have loads of spare time, but I would love to work on this. According to your 'to do' list above, my first question would be. Is this desirable in a separate repo, or integrated into this repo?

That would be great!

It will be in a separate repo, but, as far as I'm concerned, the repo will be in the PHPCSStandards organisation.

The reasons for having a separate repo is quite straight-forward:

I don't want an ever growing list of PER-x.x.x standards in this repo. As it is a living standards there could easily be a dozen PER standards (one for each version), which is unwieldy and undesirable in this repo.
The skill level needed to maintain the PER Standards package is different from the skill level needed to maintain PHPCS itself. Having it in a separate repo will allow me to give potential maintainers commit/maintain rights to that repo, without them having those rights on the PHPCS repo.
It will also allow for a more hands-off approach from me if other people take ownership of that repo.
Aside from all that, it would also allow the package to - if necessary - use other external dependencies, aside from those used by PHPCS. This is currently not an option for PHPCS itself. I can imagine, for instance, that a dependency on PHPCSExtra could be useful depending on the sniff needs of the project.

Does that answer your question ?

rikvdh commented 1 month ago

Fair enough.

PER 1.0.0 is identical to PSR-12, so this will be an "easy fix".

What is a good approach to get started? Start a repo under my own name and then migrate later to the PHPCSStandards organisation?

jrfnl commented 1 month ago

Fair enough.

PER 1.0.0 is identical to PSR-12, so this will be an "easy fix".

Correct, PER 2.0.0 is the bit which needs work (and setting up the repo and CI etc).

What is a good approach to get started? Start a repo under my own name and then migrate later to the PHPCSStandards organisation?

grin I actually already created a private repo in this organisation for it. Let me see if I can invite you to that.

Would you like to set up a call to talk things through ? If so, probably best to sort that out off-GH. You can DM me on Mastodon, X or - seeing your location - on the PHPNL Slack.

rikvdh commented 1 month ago

I'll get in touch tomorrow to schedule something. :-)

VSlokker commented 3 weeks ago

I don't have too much spare time but willing to help out on some of the work. I also don't have too much experience contributing to open source but i have to start somewhere :man_shrugging: Let me know if there is anything i can do.

PHPCSStandards / PHP_CodeSniffer