@@ -122,7 +122,7 @@ Some guidelines to get you started:
122
122
* Each line within the code sample should be max 48 characters.
123
123
* Code used in code samples should be valid PHP.
124
124
* To highlight the "good" and the "bad" bits in the code examples, surround those bits with ` <em> ...</em> ` tags.
125
- These will be removed automatically when using the text generator, but ensure highlighting of the code in Markdown/ HTML.
125
+ These will be removed automatically when using the text generator, but ensure highlighting of the code in HTML.
126
126
* The indentation in the XML file should use spaces only. Four spaces for each indent.
127
127
128
128
Make sure to test the documentation before submitting a PR by running:
@@ -162,7 +162,7 @@ and investigating those can be a good way to learn more about the source code of
162
162
163
163
#### Issues marked with "Status: help wanted"
164
164
165
- If you don't know where to start, having a browse through issues marked with the
165
+ If you don't know where to start, have a browse through issues marked with the
166
166
[ "Status: help wanted"] ( https://github.com/PHPCSStandards/PHP_CodeSniffer/labels/Status%3A%20help%20wanted ) and/or the
167
167
[ "Status: good first issue"] ( https://github.com/PHPCSStandards/PHP_CodeSniffer/labels/Status%3A%20good%20first%20issue ) labels.
168
168
@@ -236,7 +236,7 @@ For example, for the sniff named `Generic.NamingConventions.ConstructorName`:
236
236
237
237
#### Multiple test case files
238
238
239
- At times, one test _ case_ file is not enough, for instance when the sniff needs to behave differently depending on whether or code
239
+ At times, one test _ case_ file is not enough, for instance when the sniff needs to behave differently depending on whether code
240
240
is namespaced or not, or when a sniff needs to check something at the top of a file.
241
241
242
242
The test framework allows for multiple test _ case_ files.
@@ -262,6 +262,31 @@ as it is expected to be after the fixer has run.
262
262
263
263
The test framework will compare the actual fixes made with the expected fixes and will fail the tests if these don't match.
264
264
265
+ #### Tests related to parse errors/live coding
266
+
267
+ PHP_CodeSniffer can be, and is, regularly used during live coding via an IDE integration.
268
+
269
+ This means that sniffs will often need to contain extra defensive coding related to this.
270
+ It is common for sniffs to bow out early for parse errors/live coding when it cannot be reliably determined whether
271
+ the code should be flagged or not. Additionally, making auto-fixes to code in a parse error state can make things worse.
272
+
273
+ This defensive coding in a sniff should, of course, also be safeguarded via tests.
274
+
275
+ Parse/compile errors can take various forms. Some can be handled without much problems by PHPCS, some can not.
276
+
277
+ If a code snippet to be tested could lead to a broken token stream due to a parse/compile error, the code snippet should always
278
+ be put in a separate test case file by itself and be accompanied by a comment stating the test is an intentional parse error.
279
+
280
+ Example:
281
+ ``` php
282
+ <?php
283
+ // Intentional parse error (missing open parenthesis).
284
+ // This should be the only test in this file.
285
+ // Testing that the sniff is *not* triggered.
286
+ for
287
+ ```
288
+
289
+
265
290
### Submitting your pull request
266
291
267
292
Some guidelines for submitting pull requests (PRs) and improving the chance that your PR will be merged:
@@ -278,6 +303,52 @@ Some guidelines for submitting pull requests (PRs) and improving the chance that
278
303
Your time is valuable, and we appreciate your willingness to spend it on this project.
279
304
However, the maintainers time is also valuable and often, more scarce, so please be considerate of that.
280
305
306
+ #### Some git best practices
307
+
308
+ While not strictly required, it is greatly appreciated if you comply with the following git best practices:
309
+
310
+ * Prefix the commit short description with a hint as to what code is touched in the commit.
311
+ Example: If you have a bug fix for the ` Squiz.WhiteSpace.OperatorSpacing ` sniff, it is a good idea to prefix
312
+ the short description with ` Squiz/OperatorSpacing: ` .
313
+ Another example: if your PR addresses an issue with the Filter classes, prefix the short description
314
+ with ` Filters: ` or ` Filters/FilterName: ` .
315
+ Doing so will:
316
+ 1 . Allow for searches on GitHub to find all issues/PRs related to a particular sniff/area of the code more easily.
317
+ 2 . Create a more descriptive git history.
318
+ * Being wordy in the commit message is not a bad thing.
319
+ It is greatly preferable to have the details about a fix in the commit message over just having those details
320
+ in the PR description.
321
+ Code hosting platforms comes and go (think: SourceForge, PEAR), commit messages are here to stay, even if the code base
322
+ would move to another platform at some point in the future.
323
+ * Ensure that the tests (and docs) related to a particular fix are in the same commit.
324
+ It is much harder to track down what a particular code snippet in a test case file was supposed to be testing if the fix
325
+ and the tests are in separate commits.
326
+ Using atomic commits like this, also makes it much more straight forward to use tooling like ` git blame ` or ` git bisect `
327
+ or to revert a patch if necessary.
328
+ * Do not merge-back the main branch into your PR, even if your PR has been open for a while and/or has conflicts.
329
+ Spaghetti merges make for much harder to track down git history.
330
+ If your PR has not been reviewed yet, feel free to rebase at will.
331
+ Once a PR is under review, consult with the reviewer about rebasing the PR.
332
+
333
+ #### Final words
334
+
335
+ ##### Do not violate copyright
336
+
337
+ Only submit a PR with your own original code. Do NOT submit a PR containing code which you have largely copied from
338
+ an externally available sniff, unless you wrote said sniff yourself.
339
+ Open source does not mean that copyright does not apply.
340
+ Copyright infringements will not be tolerated and can lead to you being banned from the repo.
341
+
342
+ ##### Do not submit AI generated PRs
343
+
344
+ The same goes for (largely) AI-generated PRs. These are not welcome as they will be based on copyrighted code from others
345
+ without accreditation and without taking the license of the original code into account, let alone getting permission
346
+ for the use of the code or for re-licensing.
347
+
348
+ Aside from that, the experience is that AI-generated PRs will be incorrect 100% of the time and cost reviewers too much time.
349
+ Submitting a (largely) AI-generated PR will lead to you being banned from the repo.
350
+
351
+
281
352
## Licensing
282
353
283
354
By contributing code to this repository, you agree to license your code for use under the
0 commit comments