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
|
<?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 http://maven.apache.org/xsd/xdoc-2.0.xsd">
<head>
<title>Contributing</title>
<script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/2.1.3/jquery.min.js"/>
<script type="text/javascript" src="js/anchors.js"/>
<script type="text/javascript" src="js/google-analytics.js"/>
<link rel="icon" href="images/favicon.png" type="image/x-icon" />
<link rel="shortcut icon" href="images/favicon.ico" type="image/ico" />
</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="http://git-scm.com/">GIT</a>,
<a href="http://maven.apache.org">Maven</a>,
<a href="http://junit.org">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>
<p>
<b>ATTENTION:</b> any new Check that you are going to introduce you need to contribute to our
sanbox project <a href="https://github.com/sevntu-checkstyle/sevntu.checkstyle">sevntu.checkstyle</a>.
We are receiving only bug fixes for now to our main project, here is a
<a href="https://groups.google.com/forum/#!topic/checkstyle-devel/JbhfiiSqKsQ">reason</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>
</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="http://cobertura.github.io/cobertura/">Cobertura</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
Cobertura report, run the Maven command
<code>mvn cobertura:cobertura</code>.
Check results on report target/site/cobertura/index.html in project home folder.
</p>
<p>
Besides using unit testing, we obviously also use checkstyle to
check it's 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 used to generate that site.
Please recheck site and all bundles generation 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 from <a href="http://checkstyle.sourceforge.net/cmdline.html">command line</a>
</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 use <a href="https://help.github.com/articles/using-pull-requests/">Pull Request</a>
feature of <a href="https://github.com/">Github</a>.<br/>
Please provide wide description of update with detailed explanation of problem
and how you propose to resolve it.
<b>ATTENTION:</b> Please recheck that in your Pull Request there is ONLY your changes and all of them are rebased from most recent HEAD of our master branch.
</p>
<p>
<b>ATTENTION:</b> Please provide single-line meaningful message for commit with reference to github issue or Pull Request for more details.<br/>
Ideal format for message is "Issue #Number: Brief single-line message ..... .". Where NUMBER is Issue or Pull Request number at github.
<a href="https://github.com/checkstyle/checkstyle/commit/9303fd9d971eb55cdfd62686ba2f5698edb2c83e">Good example</a>
</p>
<p>
After you do Pull Request please recheck that our where is no problem from our build system:
<a href="https://travis-ci.org/checkstyle/checkstyle">Travis</a> and
<a href="https://coveralls.io/r/checkstyle/checkstyle">Coveralls</a>.
You will see that your Pull Request on Github is marked by that jobs automatically in few minutes.
</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>
|
