Skip to content

Contributing

Code quality

The project uses several plugins to ensure code quality. Most of them run during the compilation of the project. Any warnings or errors should be addressed before merging.

Checkstyle

We use Checkstyle to enforce our coding style. The configuration is located in the config/checkstyle/checkstyle.xml. It's based on Google's Java coding style. You can download the Checkstyle Plugin in the IntelliJ Plugin Store. By importing the checkstyle.xml as code style, the reformat action Ctrl+Alt+L works with it. Further, you can run Gradle tasks checkstyleMain and checkstyleTest. These tasks list problems in the shell and create an HTML report located in build/reports/checkstyle/.

All .java and .kt files should contain a copyright header. IntelliJ can automatically prepend the header for new classes using a copyright profile. To set up the functionality, import config/copyright/quick-license.xml in Settings | Editor | Copyright | CopyrightProfiles. Checkstyle will alert you if the header is missing.

To prevent Intellij from putting headers to all other kinds of files, you can create a custom shared scope in Settings | Appearance & Behaviour | Scopes with pattern file:*.java||file:*.kt and associate this with the copyright profile in Settings | Editor | Copyright.

Error Prone

Error Prone extends the Java Compiler to catch common mistakes. It's enabled by default when compiling with Gradle.

Attention

Lombok and Error Prone don't work that well together. There might be some false-positives when Lombok is used. If possible, use @SuppressWarning. Otherwise, disable the check completely in the QuickCodeQualityPlugin. Furthermore, Error Prone throws an IndexOutOfBounds exception for the pattern UnusedVariable when a Lombok annotation adds an unused field. That may usually happen with @Sl4j. In such cases, remove the annotation as it isn't used.

IntelliJ Setup

To add the plugin, start the IDE and find the Plugins dialog. Browse Repositories, choose Category: Build, and find the Error-prone plugin. Right-click and choose Download and install. The IDE will restart after you’ve exited these dialogs.

To enable Error Prone, choose Settings | Compiler | Java Compiler | Use compiler: Javac with error-prone and also make sure Settings | Compiler | Use external build is not selected.

NullAway

NullAway is a tool to help eliminate NullPointerExceptions (NPEs) in your Java code. It's built as a plugin to Error Prone. With NullAway, the compiler assumes that a variable is never null unless there is a @Nullable annotation.

Attention

@Nullable has its origin in the JSR 305 that has been dormant since 2012. Therefore, using javax.annotation.Nullable is problematic. We chose to use edu.umd.cs.findbugs.annotations.NonNull instead.

Jacoco

We use Jacoco for test coverage. The ReporterPlugin creates the task codeCoverageReport that creates a test report in build/reports/jacoco. There is an HTML report for manual inspection and an XML report that you can export to Sonarqube.

Sonarqube

There is currently no public Sonarqube project. You can run one locally and set the properties in gradle.properties.

Issues

We use GitHub issues to keep track of our tasks. Issues should always have one or more labels.

Pull Request Workflow

The master branch is protected, i.e., you can't push directly to it. We use a workflow similar to GitHub Flow, except that we squash Pull Requests (PRs). You start by creating a new local branch, committing the changes, and creating a PR on GitHub. Please don't wait till the end of creating the PR and try to keep it small(ish).

Git Branch

The branch should have a meaningful name and roughly follow the scheme TYPE/COMPONENT/TOPIC. For example, when working on a new feature in the manager, feature/mananger/new-feature could be used. You can drop TYPE and/or COMPONENT if they aren't applicable.

The name carries some importance because

  • it's used in the CI for tagging the images created for the PR. For example, the branch feature/mananger/new-feature can be deployed with the tag feature-manager-new-feature.

  • it helps find your way in git.

Pull Request

Some general guidelines regarding Pull Requests:

  • Use a meaningful title (not the default branch name) and add a short description for non-trivial changes.

  • Publish your branch early on, and create a draft PR in case it isn't ready. This allows for early feedback and helps prevent misunderstandings.

  • Keep your branch up-to-date with master, otherwise, you can't merge it.

  • If applicable, link the issues closed by this PR.

  • Add a meaningful commit message when merging the PR. For example, you can use the PR description.

  • Be careful with dependent branches/PRs. Otherwise, reviewers might have a hard time getting through the diff. See the next section for more information.

Dependent Pull Requests

Squashing merge commits is great for having a clean commit history in master. It's sometimes, however, troublesome when dealing with dependent features. The StackOverflow answer Hold on, skip merging explains the preferred workflow in such situations.

Release process

We follow SemVer versioning. A new release can be created by manually triggering the GitHub Action workflow Create release. You can specify the scope of the release, i.e., major, minor, or patch.

The process:

  • creates a release commit
  • creates a git tag
  • adds a changelog entry
  • creates a GitHub Release with the changelog entry
  • pushes a new Docker image
  • adds the corresponding Helm chart to the GitHub release
  • adds the reference to the new Helm chart to the Helm Repository
  • for minor and major releases, creates a new version in the documentation
  • creates a commit with the new dev version

Changelog

We use the github-changelog-generator to create our changelog automatically. You can find the configuration in the release workflow. We only include closed issues but not pull requests. If a closed issue shouldn't be included, label it as invalid.