error in Annotated Ruleset docs

[joachim-n]

Describe the bug

The docs page https://github.com/PHPCSStandards/PHP_CodeSniffer/wiki/Annotated-Ruleset says:

This XML file can be named anything you like, as long as it has an xml extension and complies to the ruleset.xml format. The file can be stored anywhere, making it perfect for placing under version control with a project's source code and unit tests.

I'm not sure this is true.

When I register a path to a standard with the 'installed_paths' config, I find the following:

• the ruleset XML file must be called ruleset.xml
• the ruleset.xml must be inside a folder that has the name of the ruleset, and is a child folder of the path declared to installed_paths.

In other words, this appears to be the required structure:

• path/declared/to/installed_paths
  -- MyRuleset
  --- ruleset.xml

Versions (please complete the following information)

Operating System	MacOS 13.6.8]
PHP version	8.3
PHP_CodeSniffer version	3.10.2]
Standard	custom
Install type	Composer local

Additional context

Add any other context about the problem here.

Please confirm

• I have searched the issue list and am not opening a duplicate issue.
• I have read the Contribution Guidelines and this is not a support question.
• I confirm that this bug is a bug in PHP_CodeSniffer and not in one of the external standards.
• I have verified the issue still exists in the master branch of PHP_CodeSniffer.

[jrfnl]

@joachim-n Thanks for opening this issue.

The docs are actually correct, but I do agree this can be clarified some more.

Basically it comes down to this:

• For a standard (which can have its own sniffs), there are strict naming conventions, both for the ruleset as well as the sniffs and the directory layout.
  Those naming conventions are like you mentioned above and those are outlined in the Coding Standards Tutorial.
• For a project ruleset, there are no naming conventions other than that the file is an XML file.
  The recommended way is to save the file to the project root and name it [.]phpcs.xml.dist, which will allow for it to be automatically picked up by PHPCS, but as stated in the paragraph you quoted above, the file can be called anything and placed anywhere.

Both of these are rulesets though and everything that is outlined on the Annotated Ruleset wiki page can be used in either of them.
There are, of course, best practices about what directives to add in a standard and what to add in a _project ruleset, but all directives should work just fine in either type of ruleset.

Does that clarify things ?

[joachim-n]

Thanks for the quick response!

I hadn't realised that a Standard and a ruleset are two different things.

In the docs TOC on the RHS, there's a subheading 'For coding standard creators' and the first page under that is 'Annotated Ruleset'.

I've now found the docs that explain the structure for standards in 'Coding Standard Tutorial', but that's under 'For sniff developers' heading, so I didn't look at that originally!

[jrfnl]

I hadn't realised that a Standard and a ruleset are two different things.

Well, they are and they aren't 😅. That's what makes it complicated.

For the ruleset file, there is not that much difference, other than in best practices.

The biggest difference, from a technical point of view, is really that a Standard can contain sniffs and can be "installed" and once installed, it can be referenced by name in (other/project) rulesets, including referencing individual sniffs/error codes by name (and setting properties on those etc).

What makes it complicated (terminology-wise) is that a "standard" from a functional point of view can be multiple things.

• A standard can be a descriptive document, outlining what to do and what not to do, like PSR12.
• This descriptive standard can then be codified into a PHPCS ruleset using only existing sniffs and published as a project/package ruleset (typically using a [.]phpcs.xml.dist file).
• If a project/package standard, however, is to be shared by group of projects/packages, it can be beneficial for it to be published as an (external) standard for PHPCS which can be installed, like, for example, the Doctrine Standard. This is also how the PSR-PER standard(s) are intended to work in the future (see PSR-PER 2.0.0 has been released #29).
  In that case, the standard has to have a name usable on the command-line and a ruleset.xml file.
• Depending on the need for this, this external standard for PHPCS (ruleset.xml) can then be enhanced with custom sniffs, either by contributing those to existing sniff libraries, which are already in use by the (external) standard, or by adding them to the standards package itself. An example of this is the PSR12 standard which is included in PHPCS itself, or for example, the WordPress standard.

In the docs TOC on the RHS, there's a subheading 'For coding standard creators' and the first page under that is 'Annotated Ruleset'.

I've now found the docs that explain the structure for standards in 'Coding Standard Tutorial', but that's under 'For sniff developers' heading, so I didn't look at that originally!

For the "Annotated Ruleset" page, typically, the audience would be the people working on standards as described in the second and third bullet above. ("coding standard creators").

For the "Coding Standard Tutorial" page, typically, the audience would be the people working on a standard as described in the fourth bullet ("sniff developers"), though I agree that there is information on that page which also needs to be read by people working on a standard as described in the third bullet.

Does that help explain why things are under certain headers a little better ?

I'll have a think about how to make all of this clearer, but this will probably have to wait until there is a proper website.

I do find these type of questions useful though as input for that. Happy to have your help in writing things up for a website/reviewing content and structure (by the time I get to it).