Development

Tests

We differentiate between unit tests and integration tests in our test suite. The latter has a custom annotation @IntegrationTest that should be used to mark those tests. We don't run them for draft PRs to keep the feedback loop.

Build logic

We use custom Gradle build logic to orchestrate our builds. It's located in the build-logic directory and referenced by includeBuild("build-logic") in settings.gradle.kts. The build-logic contains Quick's custom Gradle plugins.

Quick plugins

The convention module configures conventions and plugins that can be applied to a subproject.

BasePlugin

The BasePlugin is applied to all Quick projects. It configures Java, Compiler Settings, Lombok, and more.

QuickJibPlugin

The plugin applies Google's Jib plugin and sets the image location.

QuickCodeQualityPlugin

Plugin that ensures the project's code quality. This includes checkstyle, errorprone, nullaway, and jacoco. See Contributing - Code Quality for detailed information.

ReporterPlugin

The reporter plugin is applied to the root project. It allows the aggregation of data from subprojects. For example, we use this to collect and merge Jacoco test coverage for the whole project. See Operations - Registry for more information.

Gradle version catalog for dependencies

Quick uses Gradle's version catalog to define the dependencies. The list of dependencies can be found under the Gradle folder in the libs.version.toml file.

OpenAPI

The manager API is specified in the openapi directory. We use the OpenAPI generator (Version 4.3.1) to generate our python client. To download the OpenAPI JAR, please visit the OpenAPI installation documentation.

java -jar openapi-generator-cli.jar generate \
-i quick/openapi/spec/Quick-Manager-v1.yaml \
-g python \
-o quick-cli/ \
-p=generateSourceCodeOnly=true,packageName=quick_client \
--global-property apiTests=false,modelTests=false,modelDocs=false

This assumes the following directory structure:

quick-project
├── openapi-generator-cli.jar
├── quick
└── quick-cli

Documentation

The documentation is part of the main repository. It's built with mkdocs-materialize. mkdocs generates static websites from markdown files. You can find all related files in the docs directory.

Local development

mkdocs is a Python project. You can install all required dependencies with the provided requirements.txt. Run mkdocs serve from the docs directory for local development. Then you can view a live version of the documentation on http://localhost:8000. mkdocs is configured by the mkdocs.yaml file. The markdown files are in their own docs directory because mkdocs expects the files in a subdirectory.

Build

We deploy our built documentation to the gh-pages branch. For versioning, we use mike. As suggested by mike, we omit the documentation version's patch. To push a new version, run:

mike deploy x.y latest

This command also sets x.y as latest. With that, /latest redirects to /x.y. If you update an older release, omit latest, e.g.:

mike deploy x.y

We also want to redirect / to /latest/, which redirects to /x.y/. This was done with:

mike set-default latest

It creates an index.html in the root, redirecting to /latest/. Unless the file was deleted, there is no need to run the command above.

Note

These commands should only be run locally for testing purposes. Therefore, we drop the --push flag here.

Deployment

As described, mike pushes to the gh-pages branch. GitHub automatically hosts the branch on bakdata.github.io/quick.