search

squizlabs / PHP_CodeSniffer

PHP_CodeSniffer tokenizes PHP files and detects violations of a defined set of coding standards.
BSD 3-Clause "New" or "Revised" License
10.67k stars 1.48k forks source link

Feature request: Establish a pattern of providing a link to explain a lint failure #1603

Closed andrewhowdencom closed 5 years ago

andrewhowdencom commented 7 years ago

Invariably, lints are used to communicate some piece of knowledge from one developer to another. However, a lint is not a good medium to communicate the nuance of a piece of knowledge (for example, "Try not to use unserialize"). Instead, projects like shellcheck provide a key that can be looked up in a wiki that explains the lint, as well as why it exists and another way to solve the issue the lint violates.

Example: https://github.com/koalaman/shellcheck/wiki/SC1003

It would be good to establish such a pattern here. There are already keys that are provided (something like PSR2.Whitespace.Foo.Bar), which can be used as wiki pages. So, this request would consist of simply establishing a wiki that contained the necessary justification.

The GitHub wiki is a good place to host such knowledge, as in addition to the standards here, there are other project specific standards -- most of which seem to be in some way related to GitHub.

For bonus, a link could be built as first class support -- embedded in the error message shown about the link (perhaps with a shortner; l.squiz.io/PSR2.Whitespace.Foo.Bar)

Such a link could be provided optionally in the standard declaration:

<?xml version="1.0"?>
<ruleset name="PSR2">
 <description>The PSR-2 coding standard.</description>
 <arg name="tab-width" value="4"/>
 <!-- the new bit -->
 <help_url>https://l.squiz.labs/</help_url>

(Edit: 2019-01-03): I use mkdocs for this sort of documentation with other projects. Suuper simple, can be setup and pushed to netlify trivially, comes with a pretty material skin.

igorsantos07 commented 5 years ago

I'm getting here after some doc-frustration at #1752. This is a great idea indeed, but I would only vote against using the GitHub Wiki for that. It's a private wiki only open for project members, and it would make it harder for contributions and updates to land - which is one of the key-points against documentation at the mentioned issue.

This would be better placed into a GitHub Pages branch maybe, as it's just as navigable as the wiki, but it's also PR-able and possible to be automated.

gsherwood commented 5 years ago

Closing to ensure all this is tracked on #1926