Skip to content

Commit 4764e98

Browse files
qwwdfsadqwwdfsad
committed
Add documentation about our compatibility policy and experimental annotations
Fixes #859
1 parent a68376c commit 4764e98

File tree

6 files changed

+119
-32
lines changed

6 files changed

+119
-32
lines changed

‎COMPATIBILITY.md

-25
This file was deleted.

‎README.md

+1-3
Original file line numberDiff line numberDiff line change
@@ -7,9 +7,6 @@
77
Library support for Kotlin coroutines with [multiplatform](#multiplatform) support.
88
This is a companion version for Kotlin `1.3.20` release.
99

10-
**NOTE**: `0.30.2` was the last release with Kotlin 1.2 and experimental coroutines.
11-
See [COMPATIBILITY.md](COMPATIBILITY.md) for details of migration onto the stable Kotlin 1.3 coroutines.
12-
1310
```kotlin
1411
GlobalScope.launch {
1512
delay(1000)
@@ -58,6 +55,7 @@ GlobalScope.launch {
5855
* [Guide to UI programming with coroutines](ui/coroutines-guide-ui.md)
5956
* [Guide to reactive streams with coroutines](reactive/coroutines-guide-reactive.md)
6057
* [Debugging capabilities in kotlinx.coroutines](docs/debugging.md)
58+
* [Compatibility policy and experimental annotations](docs/compatibility.md)
6159
* [Change log for kotlinx.coroutines](CHANGES.md)
6260
* [Coroutines design document (KEEP)](https://github.com/Kotlin/KEEP/blob/master/proposals/coroutines.md)
6361
* [Full kotlinx.coroutines API reference](http://kotlin.github.io/kotlinx.coroutines)

‎docs/compatibility.md

+115
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
<!---
2+
/*
3+
* Copyright 2016-2019 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
4+
*/
5+
--->
6+
7+
<!--- TOC -->
8+
9+
* [Compatibility](#compatibility)
10+
* [Public API types](#public-api-types)
11+
* [Experimental API](#experimental-api)
12+
* [Obsolete API](#obsolete-api)
13+
* [Internal API](#internal-api)
14+
* [Stable API](#stable-api)
15+
* [Deprecation cycle](#deprecation-cycle)
16+
* [Using annotated API](#using-annotated-api)
17+
* [Programmatically](#programmatically)
18+
* [Gradle](#gradle)
19+
* [Maven](#maven)
20+
21+
<!--- END_TOC -->
22+
23+
## Compatibility
24+
This document describes the compatibility policy of `kotlinx.coroutines` library since version 1.0.0 and semantics of compatibility-specific annotations.
25+
26+
27+
## Public API types
28+
`kotlinx.coroutines` public API comes in five flavours: stable, experimental, obsolete, internal and deprecated.
29+
All public API except stable is marked with the corresponding annotation.
30+
31+
### Experimental API
32+
Experimental API is marked with [@ExperimentalCoroutinesApi][ExperimentalCoroutinesApi] annotation.
33+
API is marked experimental when its design has potential open questions which may eventually lead to
34+
either semantics changes of the API or its deprecation.
35+
36+
By default, most of the new API is marked as experimental and becomes stable in one of the next major releases if no new issues arise.
37+
Otherwise, either semantics is fixed without changes in ABI or API goes through deprecation cycle.
38+
39+
When using experimental API may be dangerous:
40+
* You are writing a library which depends on `kotlinx.coroutines` and want to use experimental coroutines API in a stable library API.
41+
It may lead to undesired consequences when end users of your library update their `kotlinx.coroutines` version where experimental API
42+
has slightly different semantics.
43+
* You want to build core infrastructure of the application around experimental API.
44+
45+
### Obsolete API
46+
Obsolete API is marked with [@ObsoleteCoroutinesApi][ObsoleteCoroutinesApi] annotation.
47+
Obsolete API is similar to experimental, but already known to have serious design flaws and its potential replacement,
48+
but replacement is not yet implemented.
49+
50+
The semantics of this API won't be changed, but it will go through a deprecation cycle as soon as the replacement is ready.
51+
52+
### Internal API
53+
Internal API is marked with [@InternalCoroutinesApi][InternalCoroutinesApi] or is part of `kotlinx.coroutines.internal` package.
54+
This API has no guarantees on its stability, can and will be changed and/or removed in the future releases.
55+
If you can't avoid using internal API, please report it to [issue tracker](https://github.com/Kotlin/kotlinx.coroutines/issues/new).
56+
57+
### Stable API
58+
Stable API is guaranteed to preserve its ABI and documented semantics. If at some point unfixable design flaws will be discovered,
59+
this API will go through a deprecation cycle and remain binary compatible as long as possible.
60+
61+
### Deprecation cycle
62+
When some API is deprecated, it goes through multiple stages and there is at least one major release between stages.
63+
* Feature is deprecated with compilation warning. Most of the time, proper replacement
64+
(and corresponding `replaceWith` declaration) is provided to automatically migrate deprecated usages with a help of IntelliJ IDEA.
65+
* Deprecation level is increased to `error` or `hidden`. It is no longer possible to compile new code against deprecated API,
66+
though it is still present in the ABI.
67+
* API is completely removed. While we give our best efforts not to do so and have no plans of removing any API, we still are leaving
68+
this option in case of unforeseen problems such as security holes.
69+
70+
## Using annotated API
71+
All API annotations are [kotlin.Experimental](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-experimental/index.html).
72+
It is done in order to produce compilation warning about using experimental or obsolete API.
73+
Warnings can be disabled either programmatically for a specific call site or globally for the whole module.
74+
75+
### Programmatically
76+
For a specific call-site, warning can be disabled by using [UseExperimental](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-use-experimental/index.html) annotation:
77+
```kotlin
78+
@UseExperimental(ExperimentalCoroutinesApi::class) // Disables warning about experimental coroutines API
79+
fun experimentalApiUsage() {
80+
someKotlinxCoroutinesExperimentalMethod()
81+
}
82+
```
83+
84+
### Gradle
85+
For the Gradle project, a warning can be disabled by passing a compiler flag in your `build.gradle` file:
86+
87+
```groovy
88+
tasks.withType(org.jetbrains.kotlin.gradle.tasks.AbstractKotlinCompile).all {
89+
kotlinOptions.freeCompilerArgs += ["-Xuse-experimental=kotlinx.coroutines.ExperimentalCoroutinesApi"]
90+
}
91+
92+
```
93+
94+
### Maven
95+
For the Maven project, a warning can be disabled by passing a compiler flag in your `pom.xml` file:
96+
```xml
97+
<plugin>
98+
<artifactId>kotlin-maven-plugin</artifactId>
99+
<groupId>org.jetbrains.kotlin</groupId>
100+
... your configuration ...
101+
<configuration>
102+
<args>
103+
<arg>-Xuse-experimental=kotlinx.coroutines.ExperimentalCoroutinesApi</arg>
104+
</args>
105+
</configuration>
106+
</plugin>
107+
```
108+
109+
110+
<!--- MODULE kotlinx-coroutines-core -->
111+
<!--- INDEX kotlinx.coroutines -->
112+
[ExperimentalCoroutinesApi]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-experimental-coroutines-api/index.html
113+
[ObsoleteCoroutinesApi]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-obsolete-coroutines-api/index.html
114+
[InternalCoroutinesApi]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-internal-coroutines-api/index.html
115+
<!--- END -->

‎docs/debugging.md

+2-1
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@
77
* [Stacktrace recovery](#stacktrace-recovery)
88
* [Stacktrace recovery machinery](#stacktrace-recovery-machinery)
99
* [Debug agent](#debug-agent)
10+
* [Debug agent and Android](#debug-agent-and-android)
1011

1112
<!--- END_TOC -->
1213

@@ -32,7 +33,7 @@ Stacktrace recovery is another useful feature of debug mode. It is enabled by de
3233
but can be separately disabled by setting `kotlinx.coroutines.stacktrace.recovery` system property to `false`.
3334

3435
Stacktrace recovery tries to knit asynchronous exception stacktrace with a stacktrace of the receiver by copying it, providing
35-
not only information where an exception was thrown, but also where it was asynchronously rethrown or caught .
36+
not only information where an exception was thrown, but also where it was asynchronously rethrown or caught.
3637

3738
It is easy to demonstrate with actual stacktraces of the same program that awaits asynchronous operation in `main` function:
3839

‎kotlinx-coroutines-core/common/src/Annotations.kt

-2
Original file line numberDiff line numberDiff line change
@@ -30,8 +30,6 @@ public annotation class ObsoleteCoroutinesApi
3030
* Marks declarations that are **internal** in coroutines API, which means that should not be used outside of
3131
* `kotlinx.coroutines`, because their signatures and semantics will be changing between release without any
3232
* warnings and without providing any migration aids.
33-
*
34-
* @suppress **This an internal API and should not be used from general code.**
3533
*/
3634
@Retention(value = AnnotationRetention.BINARY)
3735
@Experimental(level = Experimental.Level.ERROR)

‎kotlinx-coroutines-core/jvm/src/internal/ExceptionsConstuctor.kt

+1-1
Original file line numberDiff line numberDiff line change
@@ -65,4 +65,4 @@ private tailrec fun Class<*>.fieldsCount(accumulator: Int = 0): Int {
6565
val totalFields = accumulator + fieldsCount
6666
val superClass = superclass ?: return totalFields
6767
return superClass.fieldsCount(totalFields)
68-
}
68+
}

0 commit comments

Comments
 (0)