Create a space to document how to solve common issues for each type of linter

Issue information

From user: mparker17

Contribution record

Fork management

Problem/Motivation

As a contributor or module maintainer seeing linter warnings/errors in my code, I want to know the best way to solve common problems, so that I can make the best use of my contribution time.

We now have an excellent set of linters that will automatically run on contrib projects when maintainers enable GitLab CI. Maintainers are likely to start doing this more and more when DrupalCI is turned off on July 1st, 2024.

But, for various reasons, not every module maintainer will be familiar with the best way to fix lints... Drupal's standards and best practices have evolved over the years, some people may not have linting in their development workflow, core and contrib modules may not have the best example code.

For example, there are plenty of examples in Drupal core where \Drupal\Core\DependencyInjection\ContainerInjectionInterface::create() is implemented with return new static(....) but this will trigger an "Unsafe usage of new static" or similar lint in PHPStan. Looking at both custom and contrib code, I've seen a number of examples of how to make this lint go away, but it's unclear what the tradeoffs are for each method.

For example, for a time, the coding standards for JS files were to wrap code as follows...

(function ($, Drupal, CKEDITOR) {
// ... 
})(jQuery, Drupal, CKEDITOR);

... but the first line now throws an eslint "func-names" error in some cases, and the last line now throws an eslint "no-undef" error in some cases.

Having a list of common problems and solutions would go a long way to making it easier for maintainers ("how do I get my module to show a green checkmark in the linters stage"), and contributors ("why is the code I write not passing lints?")

(Note: this issue is distinct from #3423238: Document how to use and customize GitLabCI with mkdocs and a Pages job — 3423238 is about how to customize GitLab CI and the jobs it runs, including how to stop linter jobs from running; while this issue is about how to fix lints that a maintainer does want to run)

Proposed resolution

1. Add a section to the Drupal Wiki (or similar) to document how to solve common problems identified by the linters that run on contrib projects.
2. Add a page for what to do if composer-lint identifies issues.
3. Add a page for what to do if phpcs identifies issues (i.e.: run phpcbf, document classes, traits, and functions according to the doc standards, when it's appropriate to use phpcs:ignore or phpcs:disable, etc.)
4. Add a page for how to fix common phpstan messages (e.g.: "Unsafe usage of new static", using phpdoc comments to set types, how to set PHPStan rule levels, when to use a baseline, when it's appropriate to use phpstan-ignore-next-line, etc.)
5. Add a page for how to fix common stylelint issues
6. Add a page for how to fix common eslint issues (i.e.: download the _eslint.patch job artifact and apply it; what to do about old Drupal JS coding standards patterns that now throw errors — e.g.: (function ($, Drupal, CKEDITOR) { now throws a "func-names" error and })(jQuery, Drupal, CKEDITOR) now throws a "no-undef" error, when it's appropriate to use eslint-disable-line, etc.)
7. Add a page for how to fix common cspell issues (i.e.: how and when it's appropriate to add a project-words list; how to use Word List Syntax to ignore capitalization, etc.)

Remaining tasks

To be agreed-upon, probably something like the proposed resolution.

User interface changes

None.

API changes

None.

Data model changes

None.