Checker Framework developer manual

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.

Contents:

Directory structure

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

The repository also contains the following directories:

 docs          documentation: manual, tutorial, examples, developer docs
 maven-artifacts  artifacts to be uploaded to Maven Central

Gradle build scripts

Full instructions for building the Checker Framework from sources appear in the Checker Framework manual. This section describes the build system (the Gradle build tasks).

Don't run the gradle command, which would use your local installation of gradle. Instead, use the gradlew script in the checker-framework directory, also known as the Gradle wrapper.

Frequently-used 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 ./gradlew allTests that runs all tests everywhere. But (cd framework && ../gradlew allTests) only runs tests in framework. Alternatively, running :framework:allTests from the main directory or any subproject runs the allTests task only in the framework project.

Coding style

Code in this project follows the Google Java Style Guide (except 4 spaces are used for indentation), Michael Ernst's coding style guidelines, and Oracle's Java code conventions.

Code formatting is enforced by a Git pre-commit hook. You can configure your IDE (Eclipse or IntelliJ) to use that formatting.

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, such as by running git annotate filename.

IDE configuration

Configure Eclipse to edit the Checker Framework

These instructions are relevant if you use Eclipse as your IDE.

  1. Clone and build all projects from their sources.
  2. Download Eclipse from the official Eclipse website and install it.
  3. Run Eclipse.
  4. Enter the main Eclipse working screen and in the “File” menu, select “Import” ⇒ “General” ⇒ “Existing Projects into Workspace”.
  5. After the “Import Projects” window appears, select “Select Root Directory”, and select the parent of the $CHECKERFRAMEWORK directory.
  6. Ensure “Search for nested projects” is selected in the Options panel.
  7. Select all the projects in the folder except for “personalblog-demo”, then select “Finish” to import the projects.

Eclipse should successfully build all the imported projects. If Eclipse reports any errors, ensure you followed the instructions for cloning and building all projects.

Pull requests

Each pull request should address a single concern, rather than (say) addressing multiple concerns such as fixing a bug, adding a feature, and changing formatting. Focusing each pull request on a single concern makes the commit easier to understand and review. It also makes the commit history (after the pull request is merged) easier to understand and (if necessary) revert.

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.

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.

Also see Michael Ernst's advice about creating GitHub pull requests.

When there are related changes in the checker-framework and checker-framework-inference repositories, use the same branch name for each. The continuous integration framework uses a branch of the same name when possible. If you use different branch names in checker-framework and checker-framework-inference, then the continuous integration tests for both will fail and may mask problems.

Pull request and commit notes for maintainers

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.) As with pull requests, each commit should address a single concern. 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.

Try to review 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.

Documenting refactoring ideas

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. Clutter in the issue tracker reduces morale, makes it harder to search, and makes the project appear lower-quality than it actually is.

Version numbers for annotated libraries

We maintain annotated versions of some third-party libraries. The source code appears in a fork in the GitHub typetools organization. Binaries are hosted at Maven Central in the org.checkerframework.annotatedlib group.

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, if we already uploaded version 6.2 to Maven Central, the next version would be 6.2.0.1. This accommodates the possibility that the upstream maintainers release 6.2.1.

Making a Checker Framework release

See a separate document about the Checker Framework release process.