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.
This document assumes you are working with the GIT version of checkstyle and that you are familiar with some standard development tools ( GIT, Maven, JUnit).
To start the development - visit our Beginning Development page.
ATTENTION: if you have idea how to improve Checkstyle please create issue on our tracking system. 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 issue description, and how it is commented on fix Pull Request.
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.
To report issue please follow our best practices page - How to report an issue? ( How to report a bug?)
Project is following general maven layout and phases for build.
Generated jars will be in folder target.
Generate maven standard jar: mvn install
Generate maven standard jar and skip all validations/verifications:
mvn -P no-validations install
Generate uber jar (checkstyle-all-X.XX.jar) to use our
command line:
mvn -P assembly package
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.
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
JaCoCo.
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:
mvn test jacoco:restore-instrumented-classes jacoco:report@default-report.
Check results on report target/site/jacoco/index.html in project home folder.
Besides using unit testing, we obviously also use checkstyle to check its own code.
The Maven command mvn clean verify must pass
without any errors.
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 mvn clean site
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 our testing tool. Generated report is required to be shared in Pull Request.
Once you have made sure that your changes pass the Maven command
mvn clean verify, the code coverage is of high
standard and everything is documented, then you are ready to
submit your work.
Please create a Pull Request for your contribution. In the Pull Request description, add any explanations of the implementation nuances. Please read the Pull Request template for more requirements. ATTENTION: Please verify that the Pull Request contains ONLY your intended changes and is based on the most recent HEAD of our master branch.
ATTENTION: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
an example).
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.
"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.
After submitting a Pull Request, it will be automatically checked by Travis 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.
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.
