How to contribute

Before we get started, thank you for considering contributing to Ktor. It's awesome of you!

There are multiple ways you can contribute:

• Code
• Documentation
• Community Support
• Feedback/Issue reports

Independently of how you'd like to contribute, please make sure you read and comply with the Code of Conduct.

Code

There are many bugs and features in the Ktor backlog and you're free to pick any of them. We do recommend however starting with some of the low hanging fruit.

Building the project

Ktor is built with Gradle. Given it is multiplatform, you can build Ktor for the JVM, Native, and JavaScript.

To build the projects and produce the corresponding artifacts, use

./gradlew assemble

to run tests use

./gradlew jvmTest which runs all tests on the JVM. This is the minimum required for testing. If writing code for other platforms, the corresponding tests for these should also be run. To see the list of tasks use

./gradlew tasks

System requirements

The project requires JDK 21. Make sure you have it installed before attempting to build the project. If you use IntelliJ IDEA, you should also select JDK 21 in "Project Structure" > "Project" > "SDK"

On macOS, install Xcode and Xcode Command line tools to build Apple targets. Launch it and accept the license terms first.

If you want to run ktor-client-webrtc JVM tests on Linux, you should have pulseaudio installed. The actual audio is not played during tests, but WebRTC native library depends on it. You can install it on Ubuntu with:

sudo apt update
sudo apt install pulseaudio

sudo apt update
sudo apt install libcurl4-openssl-dev libncurses-dev

brew install curl ncurses

Optional: Android SDK

The Android SDK is optional for building Ktor. If the Android SDK is not available, Android targets will be automatically excluded from the build.

To install the Android SDK, use Android Studio or sdkmanager.

To enable Android targets, define the path to the Android SDK in the ANDROID_HOME environment variable or sdk.dir in the local.properties file:

sdk.dir=/path/to/android/sdk

Optional: CocoaPods for Apple targets

CocoaPods is optional for building Ktor. If CocoaPods is not available on macOS, Apple targets will be automatically excluded from modules that require CocoaPods dependencies (e.g., ktor-client-webrtc). Other modules will continue to build Apple targets normally.

To install CocoaPods, follow the Kotlin Multiplatform CocoaPods setup guide.

You can also specify the path to the pod executable using the kotlin.native.cocoapods.bin property in local.properties:

kotlin.native.cocoapods.bin=/path/to/pod/binary

Referencing artifacts locally

There are two ways to reference artifacts from the development Ktor locally in another project, which is usually used for debugging purposes. One of these is to publish to Maven Local. The other (and somewhat simpler), is to use the includeBuild functionality of Gradle. Reference the Ktor project from your sample project by adding the following line to your settings.gradle(.kts) file:

includeBuild("/PATH/TO/KTOR")

Importing into IntelliJ IDEA

Open the Ktor project folder — IntelliJ IDEA will detect it as a Gradle project and import it automatically. Make sure all building and test operations are delegated to Gradle under Gradle Settings.

IDE sync mode

By default, IDE sync uses light mode, which excludes native targets to reduce memory consumption and sync time. This is sufficient for working on JVM or web targets.

When working on native targets in the IDE, enable them via ktorbuild.syncMode in ~/.gradle/gradle.properties:

# Include a specific native target alongside JVM/JS
ktorbuild.syncMode=light+macosArm64

# Include all targets (requires 10 GB of RAM for Gradle Daemon)
ktorbuild.syncMode=full

See the Performance section in gradle.properties for all available options and tuning tips.

Working with Rust-based Modules Locally

The ktor-client-webrtc-rs module utilizes Rust components internally. To develop with this module in your local environment, you'll need to complete the following setup steps:

Prerequisites:

• Install Rust and Cargo on your system
• Configure your build environment by adding ktorbuild.rustCompilation=true to your global gradle.properties file

  ⚠️ Important: This setting should remain local to your development environment—do not commit this change to version control

Additional Dependencies: Depending on your target platforms, you may need to install additional dependencies for Rust cross-compilation. For comprehensive guidance on cross-compilation requirements and troubleshooting, refer to the Gobley cross-compilation documentation.

Branching Strategy

Ktor uses the following branches:

• main – Next minor or major release. Target for new features and breaking changes.
• release/* – Next patch release. Target for bug fixes.

./switch-base-branch.sh [--dry-run] [--help]

Pull Requests

Contributions are made using GitHub pull requests:

1. Fork the Ktor repository and work on your fork.
2. Create a new PR with a request to merge to the appropriate branch (see Branching Strategy).
3. Ensure that the description is clear and refers to an existing ticket/bug if applicable, prefixing the description with KTOR-{NUM}, where {NUM} refers to the YouTrack issue.
4. When contributing a new feature, provide motivation and use-cases describing why the feature not only provides value to Ktor, but also why it would make sense to be part of the Ktor framework itself.
5. If the contribution requires updates to documentation (be it updating existing contents or creating new one), please file a new ticket on YouTrack.
6. Make sure any code contributed is covered by tests and no existing tests are broken.
7. Before submitting your PR, ensure to invoke the following Gradle tasks:
   1. ./gradlew updateKotlinAbi - this will update the ABI snapshot with any public API changes
   2. ./gradlew formatKotlin - this will reformat the code to follow the style guide
   3. ./gradlew checkKotlinAbi lintKotlin - checks the output of the previous tasks

Style guides

A few things to remember:

• Your code should conform to the official Kotlin code style guide except that star imports should always be used for io.ktor.* packages. Code style is managed by EditorConfig, so make sure the EditorConfig plugin is enabled in the IDE.
• Every new source file should have a copyright header.
• Every public API (including functions, classes, objects and so on) should be documented, every parameter, property, return types and exceptions should be described properly.
• A Public API which is not intended to be used by end-users that couldn't be made private/internal due to technical reasons, should be marked with @InternalAPI annotation.

Commit messages

• Commit messages should be written in English
• They should be written in present tense using imperative mood ("Fix" instead of "Fixes", "Improve" instead of "Improved"). Add the related bug reference to a commit message (bug number after a hash character between round braces).
• When applicable, prefix the commit message with KTOR-{NUM} where {NUM} represents the YouTrack issue number

See How to Write a Git Commit Message

Design process

Whether you're thinking of a new feature or want to change the design of an existing process, before making any code contributions, please make sure you read how we handle the design process on the team.

Documentation

Ktor documentation is placed in a separate ktor-documentation repository. See the Contributing section to learn how you can contribute to Ktor docs.

Community Support

Ktor provides a number of channels for support. In addition to our support engineers, we also count on our community to help, without whom Ktor wouldn't be where it is today. If you'd like to help others, please join one of our community channels and help out. It's also a great way to learn!

Feedback/Issue Reports

Please use YouTrack to submit issues, whether these are bug reports or feature requests. Before doing so however, please take into consideration the following:

• Search for existing issues to avoid reporting duplicates.
• When submitting a bug report:
  • Test it against the most recently released version. It might have been already fixed.
  • Indicate the platform the issue relates to (JVM, Native, JavaScript), along with the operating system.
  • Include the code that reproduces the problem. Provide the complete reproducer code, yet minimize it as much as possible. If you'd like to write a unit test to reproduce the issue, even better. We love tests! However, don't be put off reporting any weird or rarely appearing issues just because you cannot consistently reproduce them.
  • If it's a behavioural bug, explain what behavior you've expected and what you've got.
• When submitting a feature request:
  • Explain why you need the feature — what's your use-case, what's your domain. Explaining the problem you face is more important than suggesting a solution. Report your problem even if you don't have any proposed solution. If there is an alternative way to do what you need, then show the code of the alternative.