1# Contributing Guidelines 2 3There are two main ways to contribute to the project — submitting issues and submitting 4fixes/changes/improvements via pull requests. 5 6## Submitting issues 7 8Both bug reports and feature requests are welcome. 9Submit issues [here](https://github.com/Kotlin/kotlinx.coroutines/issues). 10Questions about usage and general inquiries are better suited for [StackOverflow](https://stackoverflow.com) 11or the `#coroutines` channel in [KotlinLang Slack](https://surveys.jetbrains.com/s3/kotlin-slack-sign-up). 12 13## Submitting PRs 14 15We love PRs. Submit PRs [here](https://github.com/Kotlin/kotlinx.coroutines/pulls). 16However, please keep in mind that maintainers will have to support the resulting code of the project, 17so do familiarize yourself with the following guidelines. 18 19* All development (both new features and bug fixes) is performed in the `develop` branch. 20 * The `master` branch contains the sources of the most recently released version. 21 * Base your PRs against the `develop` branch. 22 * The `develop` branch is pushed to the `master` branch during release. 23 * Documentation in markdown files can be updated directly in the `master` branch, 24 unless the documentation is in the source code, and the patch changes line numbers. 25* If you fix documentation: 26 * After fixing/changing code examples in the [`docs`](docs) folder or updating any references in the markdown files 27 run the [Knit tool](#running-the-knit-tool) and commit the resulting changes as well. 28 The tests will not pass otherwise. 29 * If you plan extensive rewrites/additions to the docs, then please [contact the maintainers](#contacting-maintainers) 30 to coordinate the work in advance. 31* If you make any code changes: 32 * Follow the [Kotlin Coding Conventions](https://kotlinlang.org/docs/reference/coding-conventions.html). 33 Use 4 spaces for indentation. 34 Do not add extra newlines in function bodies: if you feel that blocks of code should be logically separated, 35 then separate them with a comment instead. 36 * [Build the project](#building) to make sure everything works and passes the tests. 37* If you fix a bug: 38 * Write the test that reproduces the bug. 39 * Fixes without tests are accepted only in exceptional circumstances if it can be shown that writing the 40 corresponding test is too hard or otherwise impractical. 41 * Follow the style of writing tests that is used in this project: 42 name test functions as `testXxx`. Don't use backticks in test names. 43* If you introduce any new public APIs: 44 * Comment on the existing issue if you want to work on it or create one beforehand. 45 Ensure that not only the issue describes a problem, but also that the proposed solution has received positive 46 feedback. Propose a solution if there isn't any. 47 PRs that add new API without a corresponding issue with positive feedback about the proposed implementation are 48 unlikely to be approved or reviewed. 49 * All new APIs must come with documentation and tests. 50 * All new APIs are initially released with the `@ExperimentalCoroutineApi` annotation and graduate later. 51 * [Update the public API dumps](#updating-the-public-api-dump) and commit the resulting changes as well. 52 It will not pass the tests otherwise. 53 * If you plan large API additions, then please start by submitting an issue with the proposed API design 54 to gather community feedback. 55 * [Contact the maintainers](#contacting-maintainers) to coordinate any extensive work in advance. 56 57## Building 58 59This library is built with Gradle. 60 61* Run `./gradlew build` to build. It also runs all the tests. 62* Run `./gradlew <module>:check` to test the module you are looking at to speed 63 things up during development. 64* Run `./gradlew <module>:jvmTest` to perform only the fast JVM tests of a multiplatform module. 65 66You can import this project into IDEA, but you have to delegate build actions 67to Gradle (in Preferences -> Build, Execution, Deployment -> Build Tools -> Gradle -> Build and run). 68 69### Environment requirements 70 71* JDK >= 11 referred to by the `JAVA_HOME` environment variable. 72* JDK 1.8 referred to by the `JDK_18` environment variable. Only used by nightly stress-tests. 73 It is OK to have `JDK_18` point to a non-1.8 JDK (e.g. `JAVA_HOME`) for external contributions. 74 75For external contributions you can, for example, add this to your shell startup scripts (e.g. `~/.zshrc`): 76```shell 77# This assumes JAVA_HOME is set already to a JDK >= 11 version 78export JDK_18="$JAVA_HOME" 79``` 80 81### Running the Knit tool 82 83* Use [Knit](https://github.com/Kotlin/kotlinx-knit/blob/main/README.md) for updates to documentation: 84 * Run `./gradlew knit` to update the example files, links, tables of content. 85 * Commit the updated documents and examples together with other changes. 86 87### Updating the public API dump 88 89* Use the [Binary Compatibility Validator](https://github.com/Kotlin/binary-compatibility-validator/blob/master/README.md) for updates to public API: 90 * Run `./gradlew apiDump` to update API index files. 91 * Commit the updated API indexes together with other changes. 92 93## Releases 94 95* The full release procedure checklist is [here](RELEASE.md). 96 97## Contacting maintainers 98 99* If something cannot be done, not convenient, or does not work — submit an [issue](#submitting-issues). 100* "How to do something" questions — [StackOverflow](https://stackoverflow.com). 101* Discussions and general inquiries — use `#coroutines` channel in [KotlinLang Slack](https://kotl.in/slack). 102