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). 10 11* Search for existing issues to avoid reporting duplicates. 12* When submitting a bug report: 13 * Test it against the most recently released version. It might have been already fixed. 14 * By default, we assume that your problem reproduces in Kotlin/JVM. Please, mention if the problem is 15 specific to Kotlin/JS or Kotlin/Native. 16 * Include the code that reproduces the problem. Provide the complete reproducer code, yet minimize it as much as possible. 17 * However, don't put off reporting any weird or rarely appearing issues just because you cannot consistently 18 reproduce them. 19 * If the bug is in behavior, then explain what behavior you've expected and what you've got. 20* When submitting a feature request: 21 * Explain why you need the feature — what's your use-case, what's your domain. 22 * Explaining the problem you face is more important than suggesting a solution. 23 Report your problem even if you don't have any proposed solution. 24 * If there is an alternative way to do what you need, then show the code of the alternative. 25 26## Submitting PRs 27 28We love PRs. Submit PRs [here](https://github.com/Kotlin/kotlinx.coroutines/pulls). 29However, please keep in mind that maintainers will have to support the resulting code of the project, 30so do familiarize yourself with the following guidelines. 31 32* All development (both new features and bug fixes) is performed in the `develop` branch. 33 * The `master` branch always contains sources of the most recently released version. 34 * Base PRs against the `develop` branch. 35 * The `develop` branch is pushed to the `master` branch during release. 36 * Documentation in markdown files can be updated directly in the `master` branch, 37 unless the documentation is in the source code, and the patch changes line numbers. 38* If you fix documentation: 39 * After fixing/changing code examples in the [`docs`](docs) folder or updating any references in the markdown files 40 run the [Knit tool](#running-the-knit-tool) and commit the resulting changes as well. 41 It will not pass the tests otherwise. 42 * If you plan extensive rewrites/additions to the docs, then please [contact the maintainers](#contacting-maintainers) 43 to coordinate the work in advance. 44* If you make any code changes: 45 * Follow the [Kotlin Coding Conventions](https://kotlinlang.org/docs/reference/coding-conventions.html). 46 Use 4 spaces for indentation. 47 * [Build the project](#building) to make sure it all works and passes the tests. 48* If you fix a bug: 49 * Write the test that reproduces the bug. 50 * Fixes without tests are accepted only in exceptional circumstances if it can be shown that writing the 51 corresponding test is too hard or otherwise impractical. 52 * Follow the style of writing tests that is used in this project: 53 name test functions as `testXxx`. Don't use backticks in test names. 54* If you introduce any new public APIs: 55 * Comment on the existing issue if you want to work on it or create one beforehand. 56 Ensure that the issue not only describes a problem, but also describes a solution that had received a positive feedback. Propose a solution if there isn't any. 57 PRs with new API, but without a corresponding issue with a positive feedback about the proposed implementation are unlikely to 58 be approved or reviewed. 59 * All new APIs must come with documentation and tests. 60 * All new APIs are initially released with `@ExperimentalCoroutineApi` annotation and are graduated later. 61 * [Update the public API dumps](#updating-the-public-api-dump) and commit the resulting changes as well. 62 It will not pass the tests otherwise. 63 * If you plan large API additions, then please start by submitting an issue with the proposed API design 64 to gather community feedback. 65 * [Contact the maintainers](#contacting-maintainers) to coordinate any big piece of work in advance. 66* Steps for contributing new integration modules are explained [here](integration/README.md#Contributing). 67 68## Building 69 70This library is built with Gradle. 71 72* Run `./gradlew build` to build. It also runs all the tests. 73* Run `./gradlew <module>:test` to test the module you are looking at to speed 74 things up during development. 75* Run `./gradlew jvmTest` to perform only fast JVM tests of the core multiplatform module. 76 77You can import this project into IDEA, but you have to delegate build actions 78to Gradle (in Preferences -> Build, Execution, Deployment -> Build Tools -> Gradle -> Runner) 79 80### Environment requirements 81 82* JDK >= 11 referred to by the `JAVA_HOME` environment variable. 83* JDK 1.8 referred to by the `JDK_18` environment variable. Only used by nightly stress-tests. 84 It is OK to have `JDK_18` to a non 1.8 JDK (e.g. `JAVA_HOME`) for external contributions. 85 86For external contributions you can for example add this to your shell startup scripts (e.g. `~/.zshrc`): 87```shell 88# This assumes JAVA_HOME is set already to a JDK >= 11 version 89export JDK_18="$JAVA_HOME" 90``` 91 92### Running the Knit tool 93 94* Use [Knit](https://github.com/Kotlin/kotlinx-knit/blob/main/README.md) for updates to documentation: 95 * Run `./gradlew knit` to update example files, links, tables of content. 96 * Commit updated documents and examples together with other changes. 97 98### Updating the public API dump 99 100* Use [Binary Compatibility Validator](https://github.com/Kotlin/binary-compatibility-validator/blob/master/README.md) for updates to public API: 101 * Run `./gradlew apiDump` to update API index files. 102 * Commit updated API indexes together with other changes. 103 104## Releases 105 106* Full release procedure checklist is [here](RELEASE.md). 107 108## Contacting maintainers 109 110* If something cannot be done, not convenient, or does not work — submit an [issue](#submitting-issues). 111* "How to do something" questions — [StackOverflow](https://stackoverflow.com). 112* Discussions and general inquiries — use `#coroutines` channel in [KotlinLang Slack](https://kotl.in/slack). 113