Merge remote-tracking branch 'origin/master' into develop

CONTRIBUTING.md

@@ -0,0 +1,113 @@
+# 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](https://github.com/Kotlin/kotlinx.coroutines/issues).
+
+* 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.
+  * By default, we assume that your problem reproduces in Kotlin/JVM. Please, mention if the problem is
+    specific to Kotlin/JS or Kotlin/Native. 
+  * Include the code that reproduces the problem. Provide the complete reproducer code, yet minimize it as much as possible.
+  * However, don't put off reporting any weird or rarely appearing issues just because you cannot consistently 
+    reproduce them.
+  * If the bug is in behavior, then 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.
+
+## Submitting PRs
+
+We love PRs. Submit PRs [here](https://github.com/Kotlin/kotlinx.coroutines/pulls).
+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 always contains sources of the most recently released version.
+  * Base 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`](docs) folder or updating any references in the markdown files
+    run the [Knit tool](#running-the-knit-tool) and commit the resulting changes as well. 
+    It will not pass the tests otherwise.
+  * If you plan extensive rewrites/additions to the docs, then please [contact the maintainers](#contacting-maintainers)
+    to coordinate the work in advance.    
+* If you make any code changes:
+  * Follow the [Kotlin Coding Conventions](https://kotlinlang.org/docs/reference/coding-conventions.html). 
+    Use 4 spaces for indentation.
+  * [Build the project](#building) to make sure it all works and passes the tests.
+* If you fix a bug:
+  * Write the test the 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:
+  * All new APIs must come with documentation and tests.
+  * All new APIs are initially released with `@ExperimentalCoroutineApi` annotation and are graduated later.
+  * [Update the public API dumps](#updating-the-public-api-dump) and commit the resulting changes as well. 
+    It will not pass the tests otherwise.
+  * If you plan large API additions, then please start by submitting an issue with the proposed API design  
+    to gather community feedback.
+  * [Contact the maintainers](#contacting-maintainers) to coordinate any big piece of work in advance.
+* Comment on the existing issue if you want to work on it. 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.
+* Steps for contributing new integration modules are explained [here](integration/README.md#Contributing).
+
+## Building
+
+This library is built with Gradle. 
+
+* Run `./gradlew build` to build. It also runs all the tests.
+* Run `./gradlew <module>:test` to test the module you are looking at to speed 
+  things up during development.
+* Run `./gradlew jvmTest` to perform only fast JVM tests of the core multiplatform module.
+
+You can import this project into IDEA, but you have to delegate build actions
+to Gradle (in Preferences -> Build, Execution, Deployment -> Build Tools -> Gradle -> Runner)
+
+### Environment requirements
+
+* JDK >= 11 referred to by the `JAVA_HOME` environment variable.
+* JDK 1.6 referred to by the `JDK_16` environment variable. 
+  It is OK to have `JDK_16` pointing to a non 1.6 JDK (e.g. `JAVA_HOME`) for external contributions.
+* JDK 1.8 referred to by the `JDK_18` environment variable. Only used by nightly stress-tests. 
+  It is OK to have `JDK_18` to a non 1.8 JDK (e.g. `JAVA_HOME`) for external contributions.
+
+For external contributions you can for example add this to your shell startup scripts (e.g. `~/.zshrc`):
+```shell
+# This assumes JAVA_HOME is set already to a JDK >= 11 version
+export JDK_16="$JAVA_HOME"
+export JDK_18="$JAVA_HOME"
+```
+
+### Running the Knit tool
+
+* Use [Knit](https://github.com/Kotlin/kotlinx-knit/blob/master/README.md) for updates to documentation:
+  * Run `./gradlew knit` to update example files, links, tables of content.
+  * Commit updated documents and examples together with other changes.
+
+### Updating the public API dump
+
+* Use [Binary Compatibility Validator](https://github.com/Kotlin/binary-compatibility-validator/blob/master/README.md) for updates to public API:
+  * Run `./gradlew apiDump` to update API index files. 
+  * Commit updated API indexes together with other changes.
+
+## Releases
+
+* Full release procedure checklist is [here](RELEASE.md).
+
+## Contacting maintainers
+
+* If something cannot be done, not convenient, or does not work &mdash; submit an [issue](#submitting-issues).
+* "How to do something" questions &mdash; [StackOverflow](https://stackoverflow.com).
+* Discussions and general inquiries &mdash; use `#coroutines` channel in [KotlinLang Slack](https://kotl.in/slack).

README.md

@@ -212,35 +212,9 @@ enableFeaturePreview('GRADLE_METADATA')
 Since Kotlin/Native does not generally provide binary compatibility between versions, 
 you should use the same version of Kotlin/Native compiler as was used to build `kotlinx.coroutines`. 
 
-## Building 
-
-This library is built with Gradle. To build it, use `./gradlew build`. 
-You can import this project into IDEA, but you have to delegate build actions
-to Gradle (in Preferences -> Build, Execution, Deployment -> Build Tools -> Gradle -> Runner)
-
-### Requirements
-
-* JDK >= 11 referred to by the `JAVA_HOME` environment variable.
-* JDK 1.6 referred to by the `JDK_16` environment variable. It is okay to have `JDK_16` pointing to `JAVA_HOME` for external contributions.
-* JDK 1.8 referred to by the `JDK_18` environment variable. Only used by nightly stress-tests. It is okay to have `JDK_18` pointing to `JAVA_HOME` for external contributions.
-
-## Contributions and releases
-
-All development (both new features and bug fixes) is performed in `develop` branch. 
-This way `master` sources always contain sources of the most recently released version.
-Please send PRs with bug fixes to `develop` branch.
-Fixes to documentation in markdown files are an exception to this rule. They are updated directly in `master`.
-
-The `develop` branch is pushed to `master` during release.
-
-* Full release procedure checklist is [here](RELEASE.md).
-* Steps for contributing new integration modules are explained [here](integration/README.md#Contributing).
-* Use [Knit](https://github.com/Kotlin/kotlinx-knit/blob/master/README.md) for updates to documentation:
-  * In project root directory run `./gradlew knit`.
-  * Commit updated documents and examples together with other changes.
-* Use [Binary Compatibility Validator](https://github.com/Kotlin/binary-compatibility-validator/blob/master/README.md) for updates to public API:
-  * In project root directory run `./gradlew apiDump`. 
-  * Commit updated API index together with other changes.
+## Building and Contributing
+
+See [Contributing Guidelines](CONTRIBUTING.md).
 
 <!--- MODULE kotlinx-coroutines-core -->
 <!--- INDEX kotlinx.coroutines -->

docs/coroutine-context-and-dispatchers.md

@@ -165,22 +165,21 @@ The Coroutine Debugger of the Kotlin plugin simplifies debugging coroutines in I
 
 > Debugging works for versions 1.3.8 or later of `kotlinx-coroutines-core`.
 
-The **Debug Tool Window** contains a **Coroutines** tab. In this tab, you can find information about both currently 
-running and suspended coroutines. The coroutines are grouped by the dispatcher they are running on. 
+The **Debug** tool window contains the **Coroutines** tab. In this tab, you can find information about both currently running and suspended coroutines. 
+The coroutines are grouped by the dispatcher they are running on.
 
-![Debugging coroutines](images/coroutine-debugger.png)
+![Debugging coroutines](images/coroutine-idea-debugging-1.png)
 
-You can:
-* Easily check the state of each coroutine.
+With the coroutine debugger, you can:
+* Check the state of each coroutine.
 * See the values of local and captured variables for both running and suspended coroutines.
 * See a full coroutine creation stack, as well as a call stack inside the coroutine. The stack includes all frames with 
 variable values, even those that would be lost during standard debugging.
+* Get a full report that contains the state of each coroutine and its stack. To obtain it, right-click inside the **Coroutines** tab, and then click **Get Coroutines Dump**.
 
-If you need a full report containing the state of each coroutine and its stack, right-click inside the **Coroutines** tab, and then
-click **Get Coroutines Dump**.
+To start coroutine debugging, you just need to set breakpoints and run the application in debug mode.
 
-Learn more about debugging coroutines in [this blog post](https://blog.jetbrains.com/kotlin/2020/07/kotlin-1-4-rc-debugging-coroutines/)
-and [IntelliJ IDEA documentation](https://www.jetbrains.com/help/idea/debug-kotlin-coroutines.html).
+Learn more about coroutines debugging in the [tutorial](https://kotlinlang.org/docs/tutorials/coroutines/debug-coroutines-with-idea.html).
 
 #### Debugging using logging
 

docs/exception-handling.md

@@ -19,7 +19,7 @@
 ## Exception Handling
 
 This section covers exception handling and cancellation on exceptions.
-We already know that cancelled coroutine throws [CancellationException] in suspension points and that it
+We already know that a cancelled coroutine throws [CancellationException] in suspension points and that it
 is ignored by the coroutines' machinery. Here we look at what happens if an exception is thrown during cancellation or multiple children of the same
 coroutine throw an exception.
 

docs/flow.md

@@ -1463,13 +1463,15 @@ fun main() = runBlocking<Unit> {
  
 A "Caught ..." message is not printed despite there being a `catch` operator: 
 
-<!--- TEST EXCEPTION  
+```text  
 Emitting 1
 1
 Emitting 2
 Exception in thread "main" java.lang.IllegalStateException: Collected 2
 	at ...
--->
+```
+
+<!--- TEST EXCEPTION -->
 
 #### Catching declaratively
 
@@ -1510,12 +1512,14 @@ fun main() = runBlocking<Unit> {
 Now we can see that a "Caught ..." message is printed and so we can catch all the exceptions without explicitly
 using a `try/catch` block: 
 
-<!--- TEST EXCEPTION  
+```text 
 Emitting 1
 1
 Emitting 2
 Caught java.lang.IllegalStateException: Collected 2
--->
+```
+
+<!--- TEST EXCEPTION -->
 
 ### Flow completion
 

gradle.properties

@@ -47,10 +47,10 @@ jsdom_global_version=3.0.2
 kotlin.incremental.multiplatform=true
 kotlin.native.ignoreDisabledTargets=true
 
-# Site deneration
+# Site generation
 jekyll_version=4.0
 
-# JS IR baceknd sometimes crashes with out-of-memory
+# JS IR backend sometimes crashes with out-of-memory
 # TODO: Remove once KT-37187 is fixed
 org.gradle.jvmargs=-Xmx2g