Skip to content

Latest commit

 

History

History
139 lines (103 loc) · 5.36 KB

CONTRIBUTING.md

File metadata and controls

139 lines (103 loc) · 5.36 KB
Raw

How to contribute to this project

❗ Important: This section contains tips for developers who are maintaining the flink-training project (not so much people doing the training).

The following sections apply on top of the Setup Instructions above.

Format code

Java

Just like Apache Flink, we use the Spotless plugin together with google-java-format to format our Java code. You can configure your IDE to automatically apply formatting upon saving with these steps:

  1. Install the google-java-format plugin and enable it for the project
  2. In the plugin settings, enable the plugin and change the code style to "AOSP" (4-space indents).
  3. Install the Save Actions plugin
  4. Enable the plugin, along with "Optimize imports" and "Reformat file".
  5. In the "Save Actions" settings page, set up a "File Path Inclusion" for .*\.java. Otherwise, you will get unintended reformatting in other files you edit.

Scala

We use the Spotless plugin for formatting Scala code as well and apply a formatting style similar to the Scalastyle configuration from Apache Flink. The code style is verified during ./gradlew check which will also print instructions how to fix the style if it does not comply with the defined format.

Ignore refactoring commits

There is a list of refactoring commits in .git-blame-ignore-revs. When looking at change annotations using git blame, it is helpful to ignore these. You can configure git and your IDE to do so with:

git config blame.ignoreRevsFile .git-blame-ignore-revs

➕ Add new exercises ➕

To add a new exercise, we recommend copying an existing one and adapting it. Make sure the new subproject's build.gradle file contains appropriate class name properties so that we can create the right tasks for running tests and solutions on the command line.

For example:

ext.javaExerciseClassName = 'org.apache.flink.training.exercises.ridesandfares.RidesAndFaresExercise'
ext.scalaExerciseClassName = 'org.apache.flink.training.exercises.ridesandfares.scala.RidesAndFaresExercise'
ext.javaSolutionClassName = 'org.apache.flink.training.solutions.ridesandfares.RidesAndFaresSolution'
ext.scalaSolutionClassName = 'org.apache.flink.training.solutions.ridesandfares.scala.RidesAndFaresSolution'

apply plugin: 'application'

mainClassName = ext.javaExerciseClassName

Useful Gradle Commands and Tricks

Clean build with all checks

./gradlew clean check shadowJar
./gradlew clean check shadowJar --no-build-cache

Force a re-run of all tests only

./gradlew cleanTest test  --no-build-cache

ℹ️ Note: Ignoring the build-cache is required if you really want to run the test again (without any changes in code). Otherwise the test tasks will just pull the latest test results from the cache.

Fix formatting

./gradlew spotlessApply
./gradlew :rides-and-fares:spotlessApply

ℹ️ Note: You do not have to remember this since ./gradlew check will not only verify the formatting and print any errors but also tell you the command to use to fix these.

Tune the Java compiler

Add the following code to the subprojects { /*...*/ } section of the build.gradle file and adapt accordingly. For example:

    tasks.withType(JavaCompile) {
        options.compilerArgs << '-Xlint:unchecked'
        options.deprecation = true
    }

ℹ️ Note: We do not add this by default to keep the training requirements low for participants and focus on the exercises.

⚠️ Deprecated Gradle Features

You may see this warning being reported from Gradle:

Deprecated Gradle features were used in this build, making it incompatible with Gradle 8.0.

You can use '--warning-mode all' to show the individual deprecation warnings and determine if they come from your own scripts or plugins.

See https://docs.gradle.org/7.1/userguide/command_line_interface.html#sec:command_line_warnings

This is currently caused by GradleUp/shadow#680 and has to be fixed by the shadow plugin developers.