/
contributing.xml
193 lines (165 loc) · 7.64 KB
/
contributing.xml
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
<?xml version="1.0" encoding="UTF-8"?>
<document xmlns="http://maven.apache.org/XDOC/2.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 https://maven.apache.org/xsd/xdoc-2.0.xsd">
<head>
<title>Contributing</title>
</head>
<body>
<section name="Content">
<macro name="toc">
<param name="fromDepth" value="1"/>
<param name="toDepth" value="1"/>
</macro>
</section>
<section name="Introduction">
<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 href="https://git-scm.com">GIT</a>,
<a href="https://maven.apache.org">Maven</a>,
<a 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 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 href="https://github.com/checkstyle/checkstyle/issues/258">
issue description</a>,
and how it is commented on fix <a href="https://github.com/checkstyle/checkstyle/pull/601">
Pull Request</a>.
</p>
</section>
<section name="Report an issue">
<p>
All functional changes in project should have registered issue and wide explanation in it.
Issue number has to be referenced in git commit message, see format below.
</p>
<p>
To report issue please follow our best 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 name="Build">
<p>
Project is following general maven layout and phases for build.
Generated jars will be in folder <code>target</code>.
</p>
<p>
Generate maven standard jar: <code>mvn install</code>
<br/>
Generate maven standard jar and skip all validations/verifications:
<code>mvn -P no-validations 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 package</code>
</p>
</section>
<section name="Quality matters">
<p>
The developer team of checkstyle is really a lazy bunch of
people. We try to avoid work as best as we can, but most of all
we try to avoid working on bugs that are reported by end users.
</p>
<p>
To that end, we use a set of development tools that ensure that
the quality of our code is kept at a fairly 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 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 test jacoco:restore-instrumented-classes jacoco:report@default-report</code>.
<br/>
Check results on report target/site/jacoco/index.html in project home 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>
The last step of verification that all works fine please do testing of your
functionality on any open-source project (Spring, Hibernate, ....).
Here is how to do it by
<a href=
"https://github.com/checkstyle/contribution/tree/master/checkstyle-tester#checkstyle-tester">
our testing tool</a>. Generated report is required to be shared in Pull Request.
</p>
</section>
<section name="Submitting your contribution">
<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 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 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 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>
We are not only lazy but at times we are also 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>
</body>
</document>