Merge branch 'master' into develop

Author: qwwdfsad

RELEASE.md

@@ -21,7 +21,7 @@ To release a new `<version>` of `kotlinx-coroutines`:
      * [`gradle.properties`](gradle.properties)
    * Make sure to **exclude** `CHANGES.md` from replacements.
 
-   As an alternative approach, you can use `./bump-version.sh old_version new_version`
+   As an alternative approach, you can use `./bump-version.sh new_version`
 
 5. Write release notes in [`CHANGES.md`](CHANGES.md):
    * Use the old releases for style guidance.
@@ -43,7 +43,7 @@ To release a new `<version>` of `kotlinx-coroutines`:
    * Get approval for it.
 
 0. On [TeamCity integration server](https://teamcity.jetbrains.com/project.html?projectId=KotlinTools_KotlinxCoroutines):
-   * Wait until "Build" configuration for committed `master` branch passes tests.
+   * Wait until "Build" configuration for committed `version-<version>` branch passes tests.
    * Run "Deploy (Configure, RUN THIS ONE)" configuration with the corresponding new version:
      - Use the `version-<version>` branch
      - Set the `DeployVersion` build parameter to `<version>`
@@ -76,6 +76,5 @@ To release a new `<version>` of `kotlinx-coroutines`:
 8. Push the updates to GitHub:<br>
    `git push`
 
-9. Build and publish the documentation for the web-site: <br>
-   * Set new value for [`kotlinx.coroutines.release.tag`](https://buildserver.labs.intellij.net/admin/editProject.html?projectId=Kotlin_KotlinSites_Builds_KotlinlangOrg_LibrariesAPIs&tab=projectParams)
-   * And run deploy [configuration](https://buildserver.labs.intellij.net/buildConfiguration/Kotlin_KotlinSites_Builds_KotlinlangOrg_KotlinCoroutinesApi?branch=%3Cdefault%3E&buildTypeTab=overview&mode=builds)
+9. Propose the website documentation update: <br>
+   * Set new value for [`KOTLINX_COROUTINES_RELEASE_TAG`](https://github.com/JetBrains/kotlin-web-site/blob/master/.teamcity/BuildParams.kt), creating a Pull Request in the website's repository. 

build.gradle

@@ -356,3 +356,7 @@ allprojects { subProject ->
                 }
             }
 }
+
+tasks.named("dokkaHtmlMultiModule") {
+    pluginsMapConfiguration.set(["org.jetbrains.dokka.base.DokkaBase": """{ "templatesDir": "${projectDir.toString().replace('\\', '/')}/dokka-templates" }"""])
+}

bump-version.sh

@@ -1,35 +1,95 @@
-#!/bin/bash
+#!/bin/sh
 
-if [ "$#" -ne 2 ]
+set -efu
+
+# the list of files that need to have the version updated in them
+#
+# limitations:
+# * no newlines in names
+# * no ' char in names
+files="
+README.md
+kotlinx-coroutines-core/README.md
+kotlinx-coroutines-debug/README.md
+kotlinx-coroutines-test/README.md
+ui/coroutines-guide-ui.md
+gradle.properties
+integration-testing/gradle.properties
+"
+
+# read gradle.properties to get the old version
+set +e
+old_version="$(git grep -hoP '(?<=^version=).*(?=-SNAPSHOT$)' gradle.properties)"
+set -e
+if [ "$?" -ne 0 ]
   then
-    echo "Use: ./bump-version old_version new_version"
-    exit
+    echo "Could not read the old version from gradle.properties." >&2
+    if [ "$#" -ne 2 ]
+      then
+        echo "Please use this form instead: ./bump-version.sh old_version new_version"
+        exit 1
+    fi
 fi
 
-old_version=$1
-new_version=$2
+# check the command-line arguments for mentions of the version
+if [ "$#" -eq 2 ]
+  then
+    echo "If you want to infer the version automatically, use the form: ./bump-version.sh new_version" >&2
+    if [ -n "$old_version" -a "$1" != "$old_version" ]
+      then
+        echo "The provided old version ($1) is different from the one in gradle.properties ($old_version)." >&2
+        echo "Proceeding anyway with the provided old version." >&2
+    fi
+    old_version=$1
+    new_version=$2
+  elif [ "$#" -eq 1 ]
+  then
+    new_version=$1
+  else
+    echo "Use: ./bump-version.sh new_version" >&2
+    exit 1
+fi
+
+
+# Escape dots, e.g. 1.0.0 -> 1\.0\.0
+escaped_old_version="$(printf "%s\n" "$old_version" | sed 's/[.]/\\./g')"
 
 update_version() {
-    echo "Updating version from '$old_version' to '$new_version' in $1"
-    sed -i.bak s/$old_version/$new_version/g $1
-    rm $1.bak
+    file=$1
+    to_undo=$2
+    echo "Updating version from '$old_version' to '$new_version' in $1" >&2
+    if [ -n "$(git diff --name-status -- "$file")" ]
+      then
+        printf "There are unstaged changes in '$file'. Refusing to proceed.\n" >&2
+        [ -z "$to_undo" ] || eval "git checkout$to_undo"
+        exit 1
+    fi
+    sed -i.bak "s/$escaped_old_version/$new_version/g" "$file"
+    rm -f "$1.bak"
 }
 
-update_version "README.md"
-update_version "kotlinx-coroutines-core/README.md"
-update_version "kotlinx-coroutines-debug/README.md"
-update_version "kotlinx-coroutines-test/README.md"
-update_version "ui/coroutines-guide-ui.md"
-update_version "gradle.properties"
-update_version "integration-test/gradle.properties"
+to_undo=$(printf "%s" "$files" | while read -r file; do
+    if [ -n "$file" ]
+      then
+        update_version "$file" "${to_undo:-}"
+        to_undo="${to_undo:-} '$file'"
+        echo -n " '$file'"
+    fi
+done)
 
-# Escape dots, e.g. 1.0.0 -> 1\.0\.0
-escaped_old_version=$(echo $old_version | sed s/[.]/\\\\./g)
-result=$(find ./ -type f \( -iname \*.properties -o -iname \*.md \) | grep -v "\.gradle" | grep -v "build" | xargs -I{} grep -H "$escaped_old_version" {} | grep -v CHANGES.md | grep -v COMPATIBILITY.md)
-if [ -z "$result" ];
+set +e
+version_mentions=$(
+    find . -type f \( -iname '*.properties' -o -iname '*.md' \) \
+    -not -iname CHANGES.md \
+    -exec git grep --fixed-strings --word "$old_version" {} +
+    )
+set -e
+if [ -z "$version_mentions" ]
 then
-    echo "Done"
+    echo "Done. To undo, run this command:" >&2
+    printf "git checkout%s\n" "$to_undo" >&2
 else
-    echo "ERROR: Previous version is present in the project: $result"
-    exit -1
+    echo "ERROR: Previous version is present in the project: $version_mentions"
+    [ -z "$to_undo" ] || eval "git checkout$to_undo"
+    exit 1
 fi

docs/images/coroutines-and-channels/aggregate.png

@@ -10,7 +10,7 @@
     <chunk include-id="coroutines">
         <toc-element id="coroutines-guide.md"/>
         <toc-element id="coroutines-basics.md" accepts-web-file-names="basics.html,coroutines-basic-jvm.html"/>
-        <toc-element toc-title="Intro to coroutines and channels – hands-on tutorial" href="https://play.kotlinlang.org/hands-on/Introduction%20to%20Coroutines%20and%20Channels/"/>
+        <toc-element id="coroutines-and-channels.md"/>
         <toc-element id="cancellation-and-timeouts.md"/>
         <toc-element id="composing-suspending-functions.md"/>
         <toc-element id="coroutine-context-and-dispatchers.md"/>