87 lines
3.1 KiB
Markdown
87 lines
3.1 KiB
Markdown
|
Developing with Coding Standards for Examples for Developers
|
||
|
|
============================================================
|
||
|
|
|
||
|
|
Examples uses mostly the same coding standards as Drupal core.
|
||
|
|
|
||
|
|
If you see a discrepancy between the coding standards tools used by core and
|
||
|
|
those used by Examples, please file an issue so that Examples can follow core.
|
||
|
|
|
||
|
|
Examples uses the `phpcs` tool to allow for checking PHP coding standards. We
|
||
|
|
use the `drupal/coder` project for Drupal-specific coding standards.
|
||
|
|
|
||
|
|
We also use `eslint` for JavaScript coding standards, and `csslint` for CSS.
|
||
|
|
|
||
|
|
Examples has a `phpcs.xml.dist` file at the root of the project. phpcs uses this
|
||
|
|
file to specify the current coding standards 'sniffs' which code in the project
|
||
|
|
must pass.
|
||
|
|
|
||
|
|
Contributors should install `phpcs` in their local Drupal installation, and then
|
||
|
|
use that to run `phpcs` against Examples as part of their development and review
|
||
|
|
process. (See details below on how to install and run this tool.)
|
||
|
|
|
||
|
|
Contributors can also patch the `phpcs.xml.dist` file itself, in order to fix
|
||
|
|
the codebase to pass a given rule or sniff. Patches which do this should be
|
||
|
|
limited to a single rule or sniff, in order make the patch easier to review.
|
||
|
|
|
||
|
|
Examples also uses the Coder project (`drupal/coder`), which adds additional
|
||
|
|
Drupal-specific coding standards. We're currently locked to Coder version
|
||
|
|
8.2.8, but this should change to reflect the state of core's coding standards.
|
||
|
|
|
||
|
|
Installing phpcs
|
||
|
|
----------------
|
||
|
|
|
||
|
|
Current versions of Drupal 8 core require phpcs and Coder as dev dependencies.
|
||
|
|
That means they're already probably installed in your core vendor/ directory.
|
||
|
|
|
||
|
|
We need to tell `phpcs` to use the Drupal coding standard provided by Coder,
|
||
|
|
because it isn't configured that way by default.
|
||
|
|
|
||
|
|
Like this:
|
||
|
|
|
||
|
|
$ cd my/drupal/root/
|
||
|
|
$ ./vendor/bin/phpcs --config-set installed_paths /full/path/to/drupal/vendor/drupal/coder/coder_sniffer/
|
||
|
|
// phpcs now knows how to find the Drupal standard. You can test it:
|
||
|
|
$ cd core
|
||
|
|
$ ../vendor/bin/phpcs -e --standard=Drupal
|
||
|
|
// Shows you a bunch of Drupal-related sniffs.
|
||
|
|
|
||
|
|
Running phpcs
|
||
|
|
-------------
|
||
|
|
|
||
|
|
Now you can run phpcs:
|
||
|
|
|
||
|
|
$ cd modules/examples
|
||
|
|
$ ../../vendor/bin/phpcs -ps
|
||
|
|
// phpcs uses Examples' phpcs.xml.dist to verify coding standards.
|
||
|
|
// -p shows you progress dots.
|
||
|
|
// -s shows you sniff errors in the report.
|
||
|
|
|
||
|
|
If there are errors, they can sometimes be fixed with `phpcbf`, which is
|
||
|
|
part of the `phpcs` package.
|
||
|
|
|
||
|
|
$ ../../vendor/bin/phpcbf
|
||
|
|
// phpcbf now performs automated fixes.
|
||
|
|
|
||
|
|
Always look at the changes to see what `phpcbf` did.
|
||
|
|
|
||
|
|
And always re-run `phpcs` in order to discover whether `phpcbf` handled all the
|
||
|
|
errors.
|
||
|
|
|
||
|
|
Installing eslint
|
||
|
|
-----------------
|
||
|
|
|
||
|
|
`eslint` is a node.js tool. You can and probably should install it globally,
|
||
|
|
since installing it locally would add files to the examples project.
|
||
|
|
Instructions available here: https://www.npmjs.com/package/eslint
|
||
|
|
|
||
|
|
Examples has an `.eslintrc` file which defines the JavaScript coding standard.
|
||
|
|
This file should be identical to the current Drupal core standard.
|
||
|
|
|
||
|
|
Running eslint
|
||
|
|
--------------
|
||
|
|
|
||
|
|
You can run eslint this way:
|
||
|
|
|
||
|
|
$ cd /path/to/examples
|
||
|
|
$ eslint .
|