Contributing Guidelines

There are two main ways to contribute to the project — submitting issues and submitting fixes/changes/improvements via pull requests.

Submitting issues

Both bug reports and feature requests are welcome. Submit issues here. Questions about usage and general inquiries are better suited for StackOverflow or the #coroutines channel in KotlinLang Slack. There, questions get answered much quicker than they do in this issue tracker, while also reducing the load on the maintainers.

Commenting on issues

Describing why you're interested in some specific issue helps us a lot with looking for the best solution. The more experiences, concerns, or suggestions get shared, the better! If you feel that something you know hasn't been said (or even if the issue discussion is too long to actually make sure of it), please do not hesitate to drop a line.

If you feel like your case was already described and you have nothing to add, please still let us know about your interest by leaving a smiley (👍)! We use these as indicators of demand.

Plese not that there is no need to leave a comment in this case, though. "+1"-style remarks or questions about the progress on an issue do not bring anything new and only create noise, complicating the job of finding insight in the discussion. Please avoid this. We reserve the right to delete such comments.

Submitting PRs

We love PRs. Submit PRs here. However, please keep in mind that maintainers will have to support the resulting code of the project, so do familiarize yourself with the following guidelines.

• All development (both new features and bug fixes) is performed in the develop branch.
  • The master branch contains the sources of the most recently released version.
  • Base your PRs against the develop branch.
  • The develop branch is pushed to the master branch during release.
  • Documentation in markdown files can be updated directly in the master branch, unless the documentation is in the source code, and the patch changes line numbers.
• If you fix documentation:
  • After fixing/changing code examples in the docs folder or updating any references in the markdown files run the Knit tool and commit the resulting changes as well. The tests will not pass otherwise.
  • If you plan extensive rewrites/additions to the docs, then please contact the maintainers to coordinate the work in advance.
• If you make any code changes:
  • Follow the Kotlin Coding Conventions. Use 4 spaces for indentation. Do not add extra newlines in function bodies: if you feel that blocks of code should be logically separated, then separate them with a comment instead.
  • Build the project to make sure everything works and passes the tests.
• If you fix a bug:
  • Note that what is a bug for some can be a feature for others. Are you truly fixing a problem? Is there an open issue about it?
  • Write the test that reproduces the bug.
  • Fixes without tests are accepted only in exceptional circumstances if it can be shown that writing the corresponding test is too hard or otherwise impractical.
  • Follow the style of writing tests that is used in this project: name test functions as testXxx. Don't use backticks in test names.
• If you introduce any new public APIs:
  • Before setting out to work on a problem, comment on the existing issue or create one, proposing a solution and gathering feedback first before implementing it. PRs that add new API without the corresponding issue with positive feedback about the proposed implementation are very unlikely to be approved or reviewed.
  • All new APIs must come with documentation and tests.
  • All new APIs are initially released with the @ExperimentalCoroutinesApi annotation and graduate later.
  • Update the public API dumps and commit the resulting changes as well. It will not pass the tests otherwise.

Building

This library is built with Gradle.

• Run ./gradlew build to build, also running all of the tests.
• Run ./gradlew <module>:check to test the module you are working with to speed things up during development.
• Run ./gradlew <module>:jvmTest to perform only the fast JVM tests of a multiplatform module.
• Run ./gradlew <module>:jvmTest -Pstress=true to run both fast and slow JVM tests.

Environment requirements

JDK >= 11 referred to by the JAVA_HOME environment variable.

Running the Knit tool

• Use Knit for updates to documentation:
  • Run ./gradlew knit to update the example files, links, tables of content.
  • Commit the updated documents and examples together with other changes.

Updating the public API dump

• Use the Kotlin Gradle Plugin's ABI validation for updates to public API:
  • Run ./gradlew updateLegacyAbi to update API index files.
  • Commit the updated API indexes together with other changes.

Releases

• The full release procedure checklist is here.

Contacting maintainers

• If something cannot be done, not convenient, or does not work — submit an issue.
• "How to do something" questions — StackOverflow.
• Discussions and general inquiries — use #coroutines channel in KotlinLang Slack.