Development workflow

The repository expects a specific edit-build-test-commit cycle that fits the size of the codebase. Trying to use it like a small Kotlin app will fight you on incremental builds and test discovery.

Branching

The default branch is master. Feature branches typically follow the pattern <author>/<short-description> or kt-XXXXX-<slug> for ticket-specific work. Long-running release branches exist (e.g., 1.9.20, 2.0.0) but day-to-day work targets master.

Editing in IntelliJ IDEA

The recommended setup is the latest IntelliJ IDEA (Community or Ultimate). After cloning, open the project root and let IDEA import the Gradle project. The first import is slow because of the size of the intellij-core/idea-full downloads.

For working with compiler test data, install the Kotlin Compiler Test Helper plugin.

The build cycle

1. Make code changes.
2. Run only the affected Gradle tasks. The repo is too large to run ./gradlew test on every edit.
3. If you added or removed a testData/*.kt file, run ./gradlew generateTests to regenerate JUnit runners. Otherwise the new test will not be discovered.
4. Run the affected test class:

   ./gradlew :compiler:test --tests "<FQCN>" -q

5. For FIR work, target compiler:fir:fir2ir:test or another FIR sub-project explicitly.

The "test before fix" pattern

A long-standing project convention (compiler/AGENTS.md): when fixing a bug, commit the test data before the fix. The test commit shows the current (broken) behavior, and the fix commit then shows the diagnostic delta. Reviewers can read the change in semantics rather than guessing what the test asserts.

Working with generated code

A lot of code in this repository is generated by the generators/ scripts:

• FIR diagnostics → compiler/fir/checkers/gen/
• Analysis API diagnostics → analysis/analysis-api-fir/gen/
• IR tree definitions → compiler/ir/ir.tree/gen/
• Compiler arguments → compiler/build-tools/kotlin-build-tools-impl/gen/ and compiler/arguments/
• Many *Generated.java test classes

Do not edit *Generated.java test files directly — regenerate them with ./gradlew generateTests. For other generated outputs, locate the generator under generators/ or the area-specific generator (e.g., compiler/fir/checkers/checkers-component-generator/) and run that.

Refactoring vs. functional change

The project insists that non-functional changes (formatting, renames, refactors) live in their own commits, separate from functional ones. This makes review and bisection dramatically easier across a codebase this large.

Working with the bootstrap

The compiler in this repository is compiled by an earlier Kotlin compiler — the bootstrap. Its version is pinned in gradle.properties and resolved from https://redirector.kotlinlang.org/maven/bootstrap. Most contributors don't touch the bootstrap; when it does change, look for "[Bootstrap]" commits.

If you need to break the bootstrap (e.g., introduce a new language feature), you generally publish a -dev build, wait for it to be released, then bump the bootstrap. Coordinate with the Release team.

Working with .api dumps

The Kotlin Gradle Plugin and several other modules check in their public API surface as .api dump files (e.g., libraries/tools/kotlin-gradle-plugin/api/all/kotlin-gradle-plugin.api). Changes to public API show up as diffs in these files; CI verifies that the dumps match the source. Update them as part of your change, not in a separate PR.

ABI validation for klibs

Multiplatform libraries that ship klibs (e.g., parts of stdlib) have their klib ABI checked. Tooling lives under libraries/tools/abi-validation/ and compiler/util-klib-abi/. Expect to update the checked-in ABI dumps when changing public APIs that produce klibs.

Reviewing large diffs

When reviewing PRs that touch generated files, focus on the generator changes; the generated outputs are mechanical. The repository's review tooling (Space MRs) folds generated diffs by default.

Working in the Native subtree

kotlin-native/ is a partial fork of the Kotlin/Native repository's history. It builds with its own build.gradle (Groovy, not Kotlin DSL), pulls in LLVM, and has separate hacking instructions in kotlin-native/HACKING.md. Set aside extra time for the first build.