-
Notifications
You must be signed in to change notification settings - Fork 8
/
contributing.html
349 lines (297 loc) · 15.6 KB
/
contributing.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
<!DOCTYPE html>
<!--
| Generated by Apache Maven Doxia Site Renderer 1.11.1 from src/xdocs/contributing.xml at 2024-12-12
| 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 – Contributing</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-12-12</span>
| <span id="projectVersion">Version: 10.21.0</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"><strong>Contributing</strong></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="#Report_an_issue">Report an issue</a></li>
<li><a href="#Build">Build</a></li>
<li><a href="#Quality_matters">Quality matters</a></li>
<li><a href="#Submitting_your_contribution">Submitting your contribution</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 a contribution of your own work to the Checkstyle
project. We welcome anything: bugfixes, new check modules, unit
tests, documentation improvements, build process simplification,
etc.
</p>
<p>
This document assumes you are working with the GIT version of
checkstyle and that you are familiar with some standard
development tools (
<a class="externalLink" href="https://git-scm.com">GIT</a>,
<a class="externalLink" href="https://maven.apache.org">Maven</a>,
<a class="externalLink" href="https://junit.org/junit5/">JUnit</a>).
</p>
<p>
To start the development - visit our
<a href="beginning_development.html">Beginning Development</a> page.
</p>
<p>
<b>ATTENTION:</b> if you have idea how to improve Checkstyle please create issue on
our <a class="externalLink" href="https://github.com/checkstyle/checkstyle/issues">tracking system</a>.
As soon as one of admins of our project approved your idea you are good to start
implementation and you will be welcome with final code contribution.
Please do not expect that we will accept any code that you send to us.
Example of ideal <a class="externalLink" href="https://github.com/checkstyle/checkstyle/issues/258">
issue description</a>,
and how it is commented on fix <a class="externalLink" href="https://github.com/checkstyle/checkstyle/pull/601">
Pull Request</a>.
</p>
</section>
<section>
<h2><a name="Report_an_issue"></a>Report an issue</h2>
<p>
All functional changes in the project must be linked to an approved issue.
The Issue number has to be referenced in the git commit message, see format below.
</p>
<p>
To report an issue please follow our practices page - <a href="report_issue.html">
How to report an issue?</a> (<a href="report_issue.html#How_to_report_a_bug.3F">
How to report a bug?</a>)
</p>
</section>
<section>
<h2><a name="Build"></a>Build</h2>
<p>
The project follows a general maven layout and phases for its build.
Generated jars will be in folder <code>target</code>.
</p>
<p>
Generate maven standard jar: <code>mvn clean install</code>
<br />
Generate maven standard jar and skip all validations/verifications:
<code>mvn -P no-validations clean install</code>
<br />
Generate uber jar (checkstyle-all-X.XX.jar) to use our
<a href="/cmdline.html">command line</a>:
<code>mvn -P assembly clean package</code>
</p>
</section>
<section>
<h2><a name="Quality_matters"></a>Quality matters</h2>
<p>
We use a set of development tools to ensure that
the quality of our code is kept at a high level. Like
most projects today, we use JUnit to test our code. However, we
do take this one step further and measure the coverage of our
unit tests using
<a class="externalLink" href="https://www.eclemma.org/jacoco/">JaCoCo</a>.
This means it is not sufficient to pass all tests, but the tests
should ideally execute each line in the code, code coverage should be 100%. To generate the
JaCoCo report, run the Maven command:
<br />
<code>mvn clean test jacoco:restore-instrumented-classes jacoco:report@default-report</code>
.
<br />
Check the results of the report in target/site/jacoco/index.html in the project's root
folder.
</p>
<p>
Besides using unit testing, we obviously also use checkstyle to
check its own code.
</p>
<p>
The Maven command <code>mvn clean verify</code> must pass
without any errors.
</p>
<p>
If you add new end user features (Check, Filter, ....), remember to document
them in JavaDoc of java classes and xdoc files that are used to generate that site.
Please recheck the site and all bundles generated by <code>mvn clean site</code>
</p>
<p>
We require regression testing for most functional changes, especially for check modules.
See our <a class="externalLink" href="https://github.com/checkstyle/contribution/tree/master/checkstyle-tester#checkstyle-tester">
regression testing tool documentation</a> for details.
</p>
</section>
<section>
<h2><a name="Submitting_your_contribution"></a>Submitting your contribution</h2>
<p>
Once you have made sure that your changes pass the Maven command
<code>mvn clean verify</code>, the code coverage is of high
standard and everything is documented, then you are ready to
submit your work.
</p>
<p>
Please create a
<a class="externalLink" href="https://help.github.com/articles/using-pull-requests/">Pull Request</a>
for your contribution. In the Pull Request description, add any explanations of the
implementation nuances. Please read the Pull Request template for more requirements.
<b>ATTENTION:</b> Please verify that the Pull Request contains ONLY your intended changes
and is based on the most recent HEAD of our master branch.
</p>
<p>
<b>ATTENTION:</b>The commit message must adhere to a certain format.
It should be "Issue #Number: Brief single-line message", where NUMBER is the issue number
at GitHub
(see
<a class="externalLink" href="https://github.com/checkstyle/checkstyle/commit/9303fd9d971eb55cdfd62686ba2f5698edb2c83e">
an example</a>).
Small changes of configuration files, documentation fixes, etc. can be contributed by
starting the commit message with one of "minor:", "config:", "infra:", "doc:",
"dependency:" or "spelling:", followed by a space and a brief single-line message.
<br />
"supplemental:" is used for PRs/commits that will support other, more significant
changes with format as "supplemental: .... for Issue #XXXX" where "XXXX" refers to the
issue that requires this supplemental commit.
</p>
<p>
After submitting a Pull Request, it will be automatically checked by
<a class="externalLink" href="https://travis-ci.org/checkstyle/checkstyle">Travis</a> and other continuous
integration (CI) services.
Therefore, please recheck after some minutes that the CIs didn't
find any issues with your changes. If there are issues, please fix them by amending
commit (not by separate commit) and provide an updated version of the same Pull Request.
</p>
<p>
At times we are busy with our day jobs. This means that
you might not always get an immediate answer. You are not being ignored,
and we value your work - we might just be too busy to review your code,
especially if it is a bit complex. If you don't get a response within two weeks,
feel free to send a reminder email about your tracker item.
</p>
</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>