If you wish to use the Checker Framework, see its user manual (HTML, PDF).
This document contains information for Checker Framework developers, including people who wish to edit its source code or make pull requests.
The checker-framework repository contains several related projects:
framework the "framework" aspects of the Checker Framework checker the type checkers provided with the Checker Framework javacutil utilities for javac dataflow a dataflow framework
Each of these directories contains Eclipse project configuration files.
The repository also contains the following directories:
docs documentation: manual, tutorial, examples, developer docs maven-artifacts artifacts to be uploaded to Maven Central
Full instructions for building the Checker Framework from sources appear in the Checker Framework manual. This section describes the build scripts themselves.
Don't run the
gradle command, which would use your local installation of gradle.
gradlew script in the
assemble: builds all jars except
jdk8.jar, including javadoc jars and fat jars that contain all dependencies.
assemble, plus runs all JUnit tests.
allTests: runs all tests.
reformat: reformats Java files.
NameOfJUnitTest: runs the JUnit test with that name; for example,
task: lists tasks; use
--allto see all tasks.
If you run a task from the main directory, then it will run that task in all
subprojects with a task by that name. So, if you run
allTests that runs all tests everywhere. But
framework && ../gradlew allTests) only runs tests in
framework. Alternatively, calling
:framework:allTests from the
main directory or any subproject has the same effect.
When editing files in the Checker Framework, see Michael Ernst's coding style guidelines. You may also wish to see Oracle's Java code conventions.
The codebase conforms to a consistent indentation style, which is enforced
by a git pre-commit hook. The pre-commit hook runs
checkFormat in the top level directory.
will format all files such that
./gradlew checkFormat succeeds.
We don't use
@author Javadoc tags in code files.
Doing so clutters the code, and is misleading once that individual
is no longer maintaining the code.
Authorship (and who has made changes recently) can be obtained from the
version control system.
Each commit should address a single issue, rather than a commit addressing multiple issues such as fixing a bug, adding a feature, and changing formatting. Focusing each commit on a single issue makes the commit easier to understand and review; it also eases diagnosis and (if necessary) rollback.
Likewise, each pull request should address a single issue.
It is acceptable to commit small, noncontroversial changes directly to master. (This policy differs from some projects, which require an issue tracker issue and a pull request for every change, however minor.) For any change where you want feedback, or where others might have useful comments or might disagree, please submit a pull request. Be conservative in your judgment; others might consider something controversial that you do not.
Work on a branch if you are going to submit a pull request. This enables others to make changes directly to your branch when that is more efficient than leaving comments in a pull request.
Try to address pull requests promptly, to avoid stalling others while waiting for your feedback. If you have been waiting for more than a week after the pull request was assigned with no feedback, then ping the assignee, wait at least another business day, and then go ahead and push your changes. It's great if reviewers can give feedback, but if they are too busy to do so, you should recognize that and move on.
Also see Michael Ernst's advice about creating GitHub pull requests.
Don't forget to update the changelog if you make changes that are worthy of telling developers about. This makes it much easier for someone to make a release.
If you have an idea for a code improvement (such as a refactoring), please document it. If it can be described concisely and is low priority, a TODO comment in the code is more appropriate than an enhancement request in the issue tracker. The code comment is more likely to be noticed by someone working with the code, and it is equally easy to search for. Furthermore, it doesn't clutter the issue tracker, which reduces morale and makes the project appear lower-quality than it actually is.
Annotated libraries should be based on a released version of the upstream library, not an arbitrary commit in the upstream library's version control system.
When making a new version of an annotated library, between upstream releases, add ".0.1" to the end of the version number. For example, we already uploaded version 6.2 to Maven Central, the next version would be 184.108.40.206. This accommodates the possibility that the upstream maintainers release 6.2.1.
See a separate document about the Checker Framework release process.