Add wiki page with info on ruleset customizations available ?

[jrfnl]

As #599 now offers a custom property which people can manipulate from the ruleset, maybe we should make info about these kind of properties a bit more easy to find for people ?

The basics are covered in https://github.com/squizlabs/PHP_CodeSniffer/wiki/Annotated-ruleset.xml

But what about having a wiki page listing the WPCS sniffs which offer adjustable properties ?
And maybe add some info on generic things which can be adjusted such as <type> too ?

[GaryJones]

Go for it.

[grappler]

Other examples

<rule ref="WordPress.WP.AlternativeFunctions">
	<properties>
		<property name="exclude" value="curl,file_get_contents"/>
	</properties>
</rule>

<rule ref="WordPress.WP.WP_DeprecatedFunctions">
	<properties>
		<property name="minimum_supported_version" value="4.3"/>
	</properties>
</rule>

<rule ref="WordPress.WP.I18n">
	<properties>
		<property name="text_domain" value="my-slug,default"/>
	</properties>
</rule>

[jrfnl]

FYI: I've got the list ready. There are just a few more things related to custom properties in the codebase which need to be adjusted before I can publish - see #765 as well.

If anyone wants to review the list already, I could create a gist with the info for now (or add it to the wiki anyway, but with a large "DRAFT WAITING FOR SOME PRS" above it ;-) ).

[JDGrimes]

I'd say you might go ahead and add it to the wiki as a "draft". Some folks will probably find it useful even if it isn't quite perfect yet. But you know best what discrepancies still exist between the list and the codebase, and how these affect the list's value at present.

[jrfnl]

I've got PRs ready for all the discrepancies, but what with merge conflicts and such, they can not be pulled all at the same time, so are waiting their turn.

Current discrepancies involve:

• Some properties which are still set to public, but really should be made protected as changing these from the ruleset would break the sniff or at the very least break the intention of the sniff.
• Some properties already in the list, but not yet added to the codebase, like the remove_only property which is being introduced in AdminBarRemoval: More thorough checking for admin bar removal and hiding #817
• Some properties, most notably the ones which merge custom arrays with preset arrays not being handled correctly internally in WPCS as discussed in The future of the WordPress_Sniff class #765 and Fix bug in WordPress_Sniffs_VIP_DirectDatabaseQuerySniff #786

Altogether it adds up to quite a lot, which makes me feel a bit uncomfortable putting it in the wiki yet.

[jrfnl]

I've put a draft version online in a gist. Be aware: The page already contains info on things which have not been merged - or even not been pulled yet -, which is why I'm not adding it to the wiki (yet).

https://gist.github.com/jrfnl/e031931849e2bce4b677f74073b87607

[grappler]

@jrfnl The gist is really good! props 😄

[jrfnl]

@grappler Thanks 😊

If anyone is interested, I created a similar list for PHPCS itself - see the upstream issue: squizlabs/PHP_CodeSniffer#1278

[GaryJones]

That is amazing - I've already been able to add some tweaks to a starter theme's phpcs.xml :-D

I'd say get that into the Wiki, but also consider adding it to version control, to make it a little easier to see changes go through.

[jrfnl]

@GaryJones Glad you find it useful. Once the PRs I have waiting have all been pulled, I'll add it to the wiki (and add links to the readme and such).
The wiki has (limited) version control - you can see previous revisions and do a diff between them. Or is that not what you meant ?

[GaryJones]

I meant, we could consider a docs directory with these .md files in, that then shipped with the project at the time of release.

[jrfnl]

@GaryJones I think that that would make it less easily discoverable as most other info is currently in the wiki. Though we could of course consider moving the whole wiki over to a docs directory ?

P.S.: the PHPCS page has been added to the PHPCS wiki in the mean time.