dom/canvas/test/webgl-conf/checkout/py/lint/README.md

   1 ## Introduction
   2
   3 We have a lint tool for catching common mistakes in test files. The tool comes from
   4 [W3C/wpt-tools](https://github.com/w3c/wpt-tools/) with modification for catching
   5 common mistakes in submitted pull request, all WebGL/sdk/tests and specified folder.
   6
   7 The copyright of this tool is belong to W3C and/or the author listed in the test
   8 file. The tool is dual-licensed under the
   9 [W3C Test Suite License](http://www.w3.org/Consortium/Legal/2008/04-testsuite-license)
  10 and [BSD 3-clause License](http://www.w3.org/Consortium/Legal/2008/03-bsd-license),
  11 which are introduced in
  12 [W3C's test suite licensing policy](http://www.w3.org/Consortium/Legal/2008/04-testsuite-copyright).
  13
  14 Now the tool can check html, htm, xhtml, xhtm, js, frag and vert files.
  15 - You can run it manually by starting the `lint.py` executable from the root of your local
  16 WebGL/sdk/tests working directory like this:
  17
  18 ```
  19 ./py/lint/lint.py
  20 ```
  21
  22 You can use the lint tool to check submitted pull request and fix the errors reported by the tool.
  23 Reviewers will not merge branches with tests that have lint errors, so you must either
  24 [fix all lint errors](#fixing-lint-errors) or update
  25 [allow-list test files] (#updating-the-allowlist) to suppress the errors.
  26
  27 ## Usage of lint tool
  28
  29 1. Check other repos, specify the repo name with `-r`, default
  30 is WebGL/sdk/tests:</br>
  31 <code>
  32 ./py/lint/lint.py -r demo-express
  33 </code>
  34 1. Check submitted pull request:</br>
  35 <code>
  36 ./py/lint/lint.py -p
  37 </code>
  38 1. Check specified folder, the specified folder must be relative path of
  39 WebGL/sdk/tests:</br>
  40 <code>
  41 ./py/lint/lint.py -d conformance/attribs
  42 </code>
  43
  44 ## Fixing lint errors
  45
  46 You must fix any errors the lint tool reports, unless an error is for
  47 something essential to a certain test or that for some other exceptional
  48 reason shouldn't prevent the test from being merged. In those cases you can
  49 update [allow-list test files](#updating-the-allowlist) to suppress the errors.
  50 Otherwise, use the details in this section to fix all errors reported.
  51
  52 * **CR AT EOL**: Test-file line ends with CR (U+000D) character; **fix**:
  53   reformat file so each line just has LF (U+000A) line ending (standard,
  54   cross-platform "Unix" line endings instead of, e.g., DOS line endings).
  55
  56 * **INDENT TABS**: Test-file line starts with one or more tab characters;
  57   **fix**: use spaces to replace any tab characters at beginning of lines.
  58
  59 * **TRAILING WHITESPACE**: Test-file line has trailing whitespace; **fix**:
  60   remove trailing whitespace from all lines in the file.
  61
  62 * **UNNECESSARY EXECUTABLE PERMISSION**: Test file contains unnecessary executable permission; **fix**:
  63   remove unnecessary executable permission of the file.
  64
  65 * **FILENAME WHITESPACE**: Test file name contains white space; **fix**:
  66   remove white space from test file name.
  67
  68 ## Updating the allowlist
  69
  70 Normally you must [fix all lint errors](#fixing-lint-errors). But in the
  71 unusual case of error reports for things essential to certain tests or that
  72 for other exceptional reasons shouldn't prevent a merge of a test, you can
  73 update and commit the `lint.allowlist` file in the WebGL/sdk/tests/py/lint/
  74 directory to suppress errors the lint tool would report for a test file.
  75
  76 To add a test file or directory to the allowlist, use the following format:
  77
  78 ```
  79 ERROR TYPE:file/name/pattern
  80 ```
  81
  82 For example, to allowlist the file `example/file.html` such that all
  83 `TRAILING WHITESPACE` errors the lint tool would report for it are
  84 suppressed, add the following line to the `lint.allowlist` file.
  85
  86 ```
  87 TRAILING WHITESPACE:example/file.html
  88 ```
  89
  90 To allowlist an entire directory rather than just one file, use the `*`
  91 wildcard. For example, to allowlist the `example` directory such that all
  92 `TRAILING WHITESPACE` errors the lint tool would report for any files in it
  93 are suppressed, add the following line to the `lint.allowlist` file.
  94
  95 ```
  96 TRAILING WHITESPACE:example/*
  97 ```
  98
  99 If needed, you can also use the `*` wildcard to express other filename
 100 patterns or directory-name patterns (just as you would when, e.g.,
 101 executing shell commands from the command line).
 102
 103 Finally, to allowlist just one line in a file, use the following format:
 104
 105 ```
 106 ERROR TYPE:file/name/pattern:line_number
 107 ```
 108
 109 For example, to allowlist just line 128 of the file `example/file.html`
 110 such that any `TRAILING WHITESPACE` error the lint tool would report for
 111 that line is suppressed, add the following to the `lint.allowlist` file.
 112
 113 ```
 114 TRAILING WHITESPACE:example/file.html:128
 115 ```