Content

Introduction

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.

Report an issue

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?)

Build

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

Quality matters

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 it's 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 used to generate that site. Please recheck site and all bundles generation 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.

Submitting your contribution

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.

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.

Bounty

Some (mostly important) issues are marked with the label has bounty. By solving such problem, you will not only help the community, but also get free beer (in monetary terms to your paypal account).

All you need to do is link your github account and paypal account through the bountysource website.