Document using wpcs in Plugin Developer Handbook

swashata commented 3 years ago

What is the new page you are requesting?

In the Plugin Developer Handbook, we have a section Developer Tools, which outlines using two WordPress Plugins. I want to add a page, describing the usage of wpcs with the WordPress-Extra sniff rules so that a plugin developer can be made aware of possible security related issues. These issues do come up during the first submission of a plugin, and could be immensely helpful for both the plugin developer and the reviewer.

How will this new page help you?

In the #pluginreview channel, we were having some discussions using wpcs, especially the WordPress-Extra sniff rules to detect and prevent potential security (sanitization, validation and escaping) issues while developing a plugin. Personally, I feel, if I knew this prior to submitting my plugin to the repository, it would’ve saved both the reviewer and me, some valuable time. I had read the guides on Plugin Security available on plugin developer’s handbook, but definitely knowing that the WordPress-Extra sniff exists to automatically detect many of such issues is very helpful.

So I would like to contribute to the plugin developer handbook outlining setting up wpcs with the sane defaults as explained in the wpcs repository. I would like to explain both the cli setup and editor setup, with some examples and screenshots. Previously I had contributed to the (now archived) eslint config wordpress repository, so I have some experience writing documentation for WordPress related dev-tools.

Please let me know how to proceed. These are the rough outline of the documentation I have in mind.

What is PHPCS and WPCS - Explain in brief the purpose of the sniffing/linting tools and how wpcs extends PHPCS with WordPress specific rules.
Setting up PHPCS through CLI - Preferable with composer (devDepencency), also installing WPCS. Linking to the GitHub wiki page for detailed instructions.
- Setup a sniffing rule for the Plugin - Creating a phpcs.xml file with a default config.
- Running phpcs through CLI - Running the command and creating a composer script.
- Gradual Adoption of Sniffing Rules - How to disable rules not relevant to the project (like style rules, which aren't applicable to a plugin). What rules to never disable (related to sanitization, escape, validation etc).
Setting up PHPCS/WPCS in your IDE - Quick overview of setting it up in VSCode. Link to the wiki page for additional editors.

theMikeD commented 3 years ago

Sounds great to me. Write it up and we'll take a look at it together.

swashata commented 3 years ago

Hello @theMikeD, I have made the first draft as the primary README.md of this repository.

https://github.com/swashata/wp-plugin-wpcs-setup

Please let me know what you think.

theMikeD commented 2 years ago

Would you prefer a PR or comments?