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 the project must be linked to an approved issue. The Issue number has to be referenced in the git commit message, see format below.
To report an issue please follow our practices page - How to report an issue? ( How to report a bug?)
The project follows a general maven layout and phases for its build.
Generated jars will be in folder target.
Generate maven standard jar: mvn clean install
Generate maven standard jar and skip all validations/verifications:
mvn -P no-validations clean install
Generate uber jar (checkstyle-all-X.XX.jar) to use our
command line:
mvn -P assembly clean package
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
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 clean test jacoco:restore-instrumented-classes jacoco:report@default-report
.
Check the results of the report in target/site/jacoco/index.html in the project's root
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
We require regression testing for most functional changes, especially for check modules. See our regression testing tool documentation for details.
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.
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.
