Improve coding standards

[SteelWagstaff]

As the product owner, I want to make sure that we're using clear and agreed upon coding standards for all the repos that we maintain to ensure that our products are more reliable.

In particular, we should

• review the coding standards we want to use for PHP (currently using humanmade/coding-standards)
• Review the rules we agree/disagree with and adjust our ruleset accordingly: https://github.com/pressbooks/coding-standards/blob/master/Pressbooks/ruleset.xml.
• Revise https://github.com/pressbooks/pressbooks/blob/dev/.github/CONTRIBUTING.md#styleguides and https://pressbooks.org/docs/coding-standards/ as needed upon updating our standards.
• Use coding standards consistently and switch to PSR across all repos #16

We agreed on:

• Research about different rules available and which one would make sense to add/avoid
• Research practices for implementing it in WP
• Propose the implementation
• Meet with tech team to agree on the implementation and rules

[richard015ar]

Progress on this:
I was reviewing: https://github.com/WordPress/WordPress-Coding-Standards
To compare with human made. I installed it locally but I had some issues trying to run it.

I booked a meeting with Dalcin and Os to have a quick brainstorming session to see what we expect here as a dev in our ruleset.

[SteelWagstaff]

@richard015ar this might be a helpful place to start if you haven't already seen it: https://engineering.hmn.md/standards/style/php/

[richard015ar]

thanks! Yes I read the intro to understand why we use it. Defintely it is the most popular and widely used for WP.
I am taking some notes on this to discuss with devs and see which rules would make sense, and also I wanna make sure we'll use it. I feel, except anyone knows something better for us, it will be the tool we will keep using it.

[richard015ar]

We had a meeting with Os and Dalcin. We agreed on keeping humanmade lib and follow the WP coding standards with some exceptions.

I will write a document with exceptions and then we'll review those and iterate over it, until we get somethings we feel comfortable. Then, I will write a PR for our coding-standards repo, and update docs where needed.

[richard015ar]

Update

I played around locally with some other libs and read a lot about the background of HM CS, WP CS and PHP CS. I also analyzed our rules, why we applied some of them and how we can centralize and avoid duplications.
I submitted a tiny PR to fix the contrib guide: pressbooks/pressbooks#2821

I also created a doc to share with the team before change our coding standard doc: https://docs.google.com/document/d/1TcltiK7mamenA1lbahyFmiEKDt_pBTcn2ZovnFZ-Ro8/edit#

TODO: Check how JS Coding Standars works (outside scope for this task, but easily managed by HM CS lib)

[richard015ar]

I published the doc: https://docs.google.com/document/d/1TcltiK7mamenA1lbahyFmiEKDt_pBTcn2ZovnFZ-Ro8/edit#heading=h.azay36inuskn which contains basic explanation about how our current coding standards work and a proposal to centralise and changes needed.
And tech team didn't had comments or suggestions on this, so it ready to go (implementation task).

In general, the current implementation makes sense and few rules are unused. Other than that, it is just avoid rules exceptions duplicated in plugins, and move that at the code level if necessary, we need to analyze repo by repo following the general proposed rules.

[richard015ar]

https://pressbooks.org/dev-docs/coding-standards/ docs looks pretty good, nothing to change there.

[SteelWagstaff]

@richard015ar thank you so much for your work on the coding standards doc! I made some edits and added some context for additional clarification: https://docs.google.com/document/d/1TcltiK7mamenA1lbahyFmiEKDt_pBTcn2ZovnFZ-Ro8/edit#heading=h.f3twoiy72t97. I don't have strong opinions about specfic rules to implement or exclude at this time and would leave that conversation to the tech team.

[SteelWagstaff]

I've updated #16 with next steps and set it as an epic. Will close this issue as completed for now.