search

WordPress / WordPress-Coding-Standards

PHP_CodeSniffer rules (sniffs) to enforce WordPress coding conventions
MIT License
2.54k stars 479 forks source link

WPCS 2.0.0 Documentation tasks #1594

Closed jrfnl closed 5 years ago

jrfnl commented 5 years ago

WordPressCS 2.0.0 contains a lot of changes and the existing documentation needs to be adjusted/updated to match the "new reality".

It would be absolutely fabulous to get more people involved to help with this.

To this end, this is a list of documentation tasks from the various WPCS 2.0.0 related issues we need help with. More information about the changes which need to be documented can be found in the linked issues:

If you're starting work on one of these action items, please leave a comment in this thread to claim the action.

Also, please leave comments if you think of action items I've forgotten, so they can be added to the list.

GaryJones commented 5 years ago
  • Go through all the wiki pages and remove/adjust any references to the VIP ruleset and sniffs.

Done, though I've hadn't changed https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards/wiki/Flagged-superglobal-usage-in-WordPress-VIP/_edit to reference ValidatedSanitizedInputSniff.

jrfnl commented 5 years ago

I've hadn't changed https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards/wiki/Flagged-superglobal-usage-in-WordPress-VIP/

@GaryJones Am I right in thinking you removed that page instead ? If so, the link to it still needs to be removed from the wiki menu (on the right side of the page).

jrfnl commented 5 years ago

Just thinking: while the SuperGlobalUsage (VIP) sniff got removed, the ValidatedSanitizedInput sniff did not. We moved that to the Security category in WPCS 1.0.0.

GaryJones commented 5 years ago

Am I right in thinking you removed that page instead ?

No - I started and had renamed it to https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards/wiki/Flagged-superglobal-usage-in-WordPress - but rather than delete, I presumed you'd want it to be refactored to be based around ValidatedSanitizedInputSniff instead. I started looking at it, but didn't get very far.

I've split this out to it's own item in the list, and marked the original item as done.

jrfnl commented 5 years ago

Ah, ok, I couldn't find the link anymore on the wiki home page and the link in the right bar menu 404s now (or at least it did yesterday when I looked), so I wasn't sure what was happening...

Might be good if that page gets rewritten to center it around both ValidatedSanitizedInput as well as NonceVerification as most people will get both those errors when a superglobal is used without security checks.

GaryJones commented 5 years ago

Might be good if that page gets rewritten to center it around both ValidatedSanitizedInput as well as NonceVerification as most people will get both those errors when a superglobal is used without security checks.

I think your expertise may be better suited for the rewrite :-)

jrfnl commented 5 years ago

I think your expertise may be better suited for the rewrite :-)

Not sure if I'm the best person for that job. Can't help but miss @JDGrimes ...

Then again, who knows, I might be able to interest @andizer to write it and show off everything he learned last week nudge :sunglasses:

jrfnl commented 5 years ago

I've just done a quick glance over the wiki pages and made some small additional adjustments. Thank you @GaryJones for doing the bulk of what needed to be done.

Aside from the Fixing errors for input data page, I consider this issue sufficiently addressed now.

As an update to the Flagged superglobal usage in WordPress would duplicate a lot of the info on the "Fixing errors for input data" page, I think the "Flagged superglobal usage in WordPress" should be removed in favour of improving the "Fixing errors for input data" page (where necessary).

GaryJones commented 5 years ago

As an update to the Flagged superglobal usage in WordPress would duplicate a lot of the info on the "Fixing errors for input data" page, I think the "Flagged superglobal usage in WordPress" should be removed in favour of improving the "Fixing errors for input data" page (where necessary).

Agreed. The "Flagging superglobals..." page seemed quite specific. Go ahead and delete it when you're ready. May also need to see if any of these now-deleted wiki pages are referenced in the code base (comment, etc.)

jrfnl commented 5 years ago

May also need to see if any of these now-deleted wiki pages are referenced in the code base (comment, etc.)

Just checked & no links to the wiki found in inline docs, only in the Readme/Contributing/Changelog/sample ruleset. Most to either the PHPCS wiki, the WPCS wiki homepage, the customizable properties page or the whitelist flags page. As far as I can see no (direct) links to any of the wiki pages we're removing.

It may be worth checking if those links are all still valid, but especially for the changelog, I'm not too concerned, we don't need to rewrite history.

jrfnl commented 5 years ago

I've removed the "Flagging superglobals" page + removed both that page as well as the other removed page (PHPCS3 & including individual sniffs) from the Wiki sidebar.

IMO that finishes what needed to be done here.