-
Notifications
You must be signed in to change notification settings - Fork 8
/
report_issue.html
431 lines (355 loc) · 16.7 KB
/
report_issue.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
<!DOCTYPE html>
<!--
| Generated by Apache Maven Doxia Site Renderer 1.11.1 from src/xdocs/report_issue.xml at 2024-08-30
| Rendered using Apache Maven Default Skin
-->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="generator" content="Apache Maven Doxia Site Renderer 1.11.1" />
<title>checkstyle – How to report an issue ?</title>
<link rel="stylesheet" href="./css/maven-base.css" />
<link rel="stylesheet" href="./css/maven-theme.css" />
<link rel="stylesheet" href="./css/site.css" />
<link rel="stylesheet" href="./css/print.css" media="print" />
<script type="text/javascript" src="./js/checkstyle.js"></script>
<script type="text/javascript"
src="https://ajax.googleapis.com/ajax/libs/jquery/2.1.3/jquery.min.js"></script>
<script type="text/javascript" src="./js/anchors.js"></script>
<script type="text/javascript" src="./js/google-analytics.js"></script>
<link rel="icon" href="./images/favicon.png" type="image/x-icon" />
<link rel="shortcut icon" href="./images/favicon.ico" type="image/ico" />
</head>
<body class="composite">
<div id="banner">
<a href="./" id="bannerLeft" title="Checkstyle"><img src="images/header-checkstyle-logo.png" alt="Checkstyle"/></a><a href="./" id="bannerRight" title="Checkstyle"><img src="images/header-right-ruller.png" alt="Checkstyle"/></a> <div class="clear">
<hr/>
</div>
</div>
<div id="breadcrumbs">
<div class="xright"><a href="" title="toTop">toTop</a> | <span id="publishDate">Last Published: 2024-08-30</span>
| <span id="projectVersion">Version: 10.18.1</span>
</div>
<div class="clear">
<hr/>
</div>
</div>
<div id="leftColumn">
<div id="navcolumn">
<h5>About</h5>
<ul>
<li class="none"><a href="index.html" title="Checkstyle">Checkstyle</a></li>
<li class="none"><a href="releasenotes.html" title="Release Notes">Release Notes</a></li>
<li class="none"><a href="consulting.html" title="Consulting">Consulting</a></li>
<li class="none"><a href="sponsoring.html" title="Sponsoring">Sponsoring</a></li>
</ul>
<h5>Documentation</h5>
<ul>
<li class="expanded"><a href="config.html" title="Configuration">Configuration</a>
<ul>
<li class="none"><a href="property_types.html" title="Property Types">Property Types</a></li>
<li class="none"><a href="config_system_properties.html" title="System Properties">System Properties</a></li>
</ul></li>
<li class="expanded"><a href="running.html" title="Running">Running</a>
<ul>
<li class="none"><a href="anttask.html" title="Ant Task">Ant Task</a></li>
<li class="none"><a href="cmdline.html" title="Command Line">Command Line</a></li>
</ul></li>
<li class="expanded"><a href="checks.html" title="Checks">Checks</a>
<ul>
<li class="collapsed"><a href="checks/annotation/index.html" title="Annotations">Annotations</a></li>
<li class="collapsed"><a href="checks/blocks/index.html" title="Block Checks">Block Checks</a></li>
<li class="collapsed"><a href="checks/design/index.html" title="Class Design">Class Design</a></li>
<li class="collapsed"><a href="checks/coding/index.html" title="Coding">Coding</a></li>
<li class="collapsed"><a href="checks/header/index.html" title="Headers">Headers</a></li>
<li class="collapsed"><a href="checks/imports/index.html" title="Imports">Imports</a></li>
<li class="collapsed"><a href="checks/javadoc/index.html" title="Javadoc Comments">Javadoc Comments</a></li>
<li class="collapsed"><a href="checks/metrics/index.html" title="Metrics">Metrics</a></li>
<li class="collapsed"><a href="checks/misc/index.html" title="Miscellaneous">Miscellaneous</a></li>
<li class="collapsed"><a href="checks/modifier/index.html" title="Modifiers">Modifiers</a></li>
<li class="collapsed"><a href="checks/naming/index.html" title="Naming Conventions">Naming Conventions</a></li>
<li class="collapsed"><a href="checks/regexp/index.html" title="Regexp">Regexp</a></li>
<li class="collapsed"><a href="checks/sizes/index.html" title="Size Violations">Size Violations</a></li>
<li class="collapsed"><a href="checks/whitespace/index.html" title="Whitespace">Whitespace</a></li>
</ul></li>
<li class="collapsed"><a href="filters/index.html" title="Filters">Filters</a></li>
<li class="collapsed"><a href="filefilters/index.html" title="File Filters">File Filters</a></li>
<li class="expanded"><a href="style_configs.html" title="Style Configurations">Style Configurations</a>
<ul>
<li class="none"><a href="google_style.html" title="Google's Style">Google's Style</a></li>
<li class="none"><a href="sun_style.html" title="Sun's Style">Sun's Style</a></li>
</ul></li>
</ul>
<h5>Developers</h5>
<ul>
<li class="expanded"><a href="extending.html" title="Extending Checkstyle">Extending Checkstyle</a>
<ul>
<li class="none"><a href="writingchecks.html" title="Writing Checks">Writing Checks</a></li>
<li class="none"><a href="writingjavadocchecks.html" title="Writing Javadoc Checks">Writing Javadoc Checks</a></li>
<li class="none"><a href="writingfilters.html" title="Writing Filters">Writing Filters</a></li>
<li class="none"><a href="writingfilefilters.html" title="Writing File Filters">Writing File Filters</a></li>
<li class="none"><a href="writinglisteners.html" title="Writing Listeners">Writing Listeners</a></li>
</ul></li>
<li class="none"><a href="contributing.html" title="Contributing">Contributing</a></li>
<li class="expanded"><a href="beginning_development.html" title="Beginning Development">Beginning Development</a>
<ul>
<li class="none"><a href="eclipse.html" title="Eclipse IDE">Eclipse IDE</a></li>
<li class="none"><a href="netbeans.html" title="NetBeans IDE">NetBeans IDE</a></li>
<li class="none"><a href="idea.html" title="IntelliJ IDE">IntelliJ IDE</a></li>
</ul></li>
<li class="none"><a href="apidocs/index.html" title="Javadoc">Javadoc</a></li>
</ul>
<h5>Project Documentation</h5>
<ul>
<li class="collapsed"><a href="project-info.html" title="Project Information">Project Information</a></li>
<li class="collapsed"><a href="project-reports.html" title="Project Reports">Project Reports</a></li>
</ul>
<a href="https://github.com/checkstyle/checkstyle" title="GitHub" class="poweredBy">
<img class="poweredBy" alt="GitHub" src="images/github_logo_social_coding_outlined.png" />
</a>
<a href="https://twitter.com/checkstyle_java/" title="Twitter" class="poweredBy">
<img class="poweredBy" alt="Twitter" src="images/twitter_button.png" />
</a>
<a href="https://stackoverflow.com/questions/tagged/checkstyle" title="Stackoverflow" class="poweredBy">
<img class="poweredBy" alt="Stackoverflow" src="images/stackoverflow.jpeg" />
</a>
<a href="https://groups.google.com/forum/#!forum/checkstyle" title="GoogleGroups" class="poweredBy">
<img class="poweredBy" alt="GoogleGroups" src="images/groups.png" />
</a>
<a href="https://www.ej-technologies.com/products/jprofiler/overview.html" title="JProfiler" class="poweredBy">
<img class="poweredBy" alt="JProfiler" src="https://www.ej-technologies.com/images/product_banners/jprofiler_medium.png" />
</a>
</div>
</div>
<div id="bodyColumn">
<div id="contentBox">
<section>
<h2><a name="Content"></a>Content</h2>
<ul>
<li><a href="#Content">Content</a></li>
<li><a href="#Introduction">Introduction</a></li>
<li><a href="#How_to_report_a_bug.3F">How to report a bug?</a></li>
<li><a href="#How_to_request_new_feature_for_existing_functionality.3F">How to request new feature for existing functionality?</a></li>
<li><a href="#How_to_request_new_Check.2FModule.3F">How to request new Check/Module?</a></li></ul>
</section>
<section>
<h2><a name="Introduction"></a>Introduction</h2>
<p>
Hey, good to see you on this page. It means that you are considering reporting an
issue to the Checkstyle project. We welcome anything: bug reports, feature requests
to existing functionality, new Check ideas, etc.
</p>
<p>
Our issue tracker system is at GitHub -
<a class="externalLink" href="https://github.com/checkstyle/checkstyle/issues">
https://github.com/checkstyle/checkstyle/issues</a>.
</p>
</section>
<section>
<h2><a name="How_to_report_a_bug.3F"></a>How to report a bug?</h2>
<p>
First and foremost, do not think that your issue is obvious and doesn't need details.<br />
Even a tiny issue needs all details
(Check name, config with options, source file, Checkstyle version) and context to be
shared with us.
</p>
<p>
The best way to report an Issue is to reproduce it by our
<a href="cmdline.html#Download_and_Run">
Command Line Interface (CLI)</a>. It is the most minimalistic way to launch Checkstyle.<br />
PLEASE use our latest released version.
</p>
<p>
Our project is NOT responsible for problems at any extension or plugins.<br />
Checkstyle is library that is used by number of IDEs and static analysis services.<br />
We fix problems that are only reproducible on latest release.
</p>
<p>
We need minimized but compilable Java file and minimized config with one Check
that cause problem.<br />
We do not need real source code. Any obfuscation of your super secret code is OK.<br />
Link to your source code would be awesome.
Code has to be compilable, in other case behaviour could be strange.<br />
Always specify what is expected.
</p>
<p>
Example of report that we expect (you can skip <code>-Duser.language=en
-Duser.country=US</code> if your default locale is English):
</p>
<div class="source">
<pre>
Check documentation: https://checkstyle.org/checks/whitespace/whitespacearound.html#WhitespaceAround
/var/tmp $ javac Test.java
/var/tmp $ cat Test.java
public class Test{ // Doesn't warn - incorrect
private static final int SOMETHING = 1;
}
/var/tmp $ cat config.xml
<?xml version="1.0"?>
<!DOCTYPE module PUBLIC
"-//Checkstyle//DTD Checkstyle Configuration 1.3//EN"
"https://checkstyle.org/dtds/configuration_1_3.dtd">
<module name="Checker">
<module name="TreeWalker">
<module name="WhitespaceAround">
<property name="allowEmptyTypes" value="true"/>
</module>
</module>
</module>
/var/tmp $ RUN_LOCALE="-Duser.language=en -Duser.country=US"
/var/tmp $ java $RUN_LOCALE -jar checkstyle-X.XX-all.jar -c config.xml Test.java
Starting audit...
Audit done.
Expected: violation on first line.
/var/tmp/Test.java:1:28: error: '{' is not preceded with whitespace.
</pre></div>
<p>
For Windows users, please use "type" command instead of "cat".
Example of report that we expect:
</p>
<div class="source">
<pre>
Check documentation: https://checkstyle.org/checks/misc/indentation.html
D:\>type config.xml
<?xml version="1.0"?>
<!DOCTYPE module PUBLIC
"-//Puppy Crawl//DTD Check Configuration 1.3//EN"
"https://checkstyle.org/dtds/configuration_1_3.dtd">
<module name="Checker">
<module name="TreeWalker">
<module name="Indentation"/>
</module>
</module>
D:\>type Test.java
class Test {
void method() {
try { return; // violation, but it is not expected
}
catch (Exception e) { return; // no violation, but expected
}
}
}
D:\>set RUN_LOCALE="-Duser.language=en -Duser.country=US"
D:\>java %RUN_LOCALE% -jar checkstyle-X.XX-all.jar -c config.xml Test.java
Starting audit...
[ERROR] D:\Test.java:3: 'try' child has incorrect indentation level 8,
expected level should be 12. [Indentation]
Audit done.
Expected: A violation on line 5 and nowhere else.
D:\Test.java:5: 'catch' child has incorrect indentation level 8,
expected level should be 12. [Indentation]
</pre></div>
<p>
More Examples:
<a class="externalLink" href="https://github.com/checkstyle/checkstyle/issues/8856#issue-711050333">
Example 1
</a>,
<a class="externalLink" href="https://github.com/checkstyle/checkstyle/issues/8808#issue-695386080">
Example 2
</a>
</p>
</section>
<section>
<h2><a name="How_to_request_new_feature_for_existing_functionality.3F"></a>How to request new feature for existing functionality?</h2>
<p>
Please always specify exact name of the Check/Module.
</p>
<p>
Please provide a clear and detailed description of the problem and describe what
you would want to happen instead. Relevant chunks of code and config that you currently
have will definitely facilitate understanding. Any other context or
screenshots which elaborate further on the relevance and rationale behind
the new feature may also be added.
</p>
<p>
Imagine that everything is possible and propose name of the new option and its behaviour.
Do not think that your issue is so obvious.
</p>
<p>
Example of Feature Request/Enhancement that we expect:
</p>
<div class="source">
<pre>
Check documentation: https://checkstyle.org/checks/whitespace/whitespacearound.html#WhitespaceAround
Describe the problem in detail:
/var/tmp $ javac Test.java
/var/tmp $ cat config.xml
#[[PLACE YOUR OUTPUT HERE, IF NEW PROPERTY IS PROPOSED PUT IT INSIDE CONFIG AS IT ALREADY EXISTS]]
/var/tmp $ cat Test.java
public class Test { // Note
private static final int SOMETHING = 1;
}
/var/tmp $ java $RUN_LOCALE -jar checkstyle-X.XX-all.jar -c config.xml Test.java
#[[PLACE YOUR IMAGINARY OUTPUT HERE]]
Describe how the additional functionality will solve the problem:
Additional context, screenshots or examples:
</pre></div>
<p>
More Examples:
<a class="externalLink" href="https://github.com/checkstyle/checkstyle/issues/3201#issue-155988267">
Example 1
</a>,
<a class="externalLink" href="https://github.com/checkstyle/checkstyle/issues/6582#issue-421909457">
Example 2
</a>
</p>
</section>
<section>
<h2><a name="How_to_request_new_Check.2FModule.3F"></a>How to request new Check/Module?</h2>
<p>
Please provide detailed description of problem.
</p>
<p>
You have to provide examples of code and expected violations on them.
The more examples the better.
</p>
<p>
Explain the rationale behind implementing the new check with relevant
references (if possible).
</p>
<p>
Feel free to propose a name for the new Check, along with all its attributes.
Example of good new Check proposal is
<a class="externalLink" href="https://github.com/checkstyle/checkstyle/issues/5899">#5899</a>.
</p>
<p>
If you have open source project, please give a link to the whole java file.
</p>
<p>
Example of Check/Module Request that we expect:
</p>
<div class="source">
<pre>
Describe the problem in detail:
/var/tmp $ cat config.xml
<module name="YourNewModule">
<property name="yourPossibleProperty1" value="true"/>
<property name="yourPossibleProperty2" value="123"/>
</module>
/var/tmp $ javac Test.java
/var/tmp $ cat Test.java
public class Test { // To be checked
private static final int SOMETHING = 1;
}
/var/tmp $ java $RUN_LOCALE -jar checkstyle-X.XX-all.jar -c config.xml Test.java
#[[PLACE YOUR IMAGINARY OUTPUT HERE]]
Describe how the new check will solve the problem. Mention the required properties
and their behaviour.
Additional context, screenshots or examples:
</pre></div>
</section>
</div>
</div>
<div class="clear">
<hr/>
</div>
<div id="footer">
<div class="xright">
Copyright © 2001–2024.. </div>
<div class="clear">
<hr/>
</div>
</div>
</body>
</html>