Skip to content

Commit bc3ce4b

Browse files
qwwdfsadqwwdfsad
committed
Add documentation about our compatibility policy and experimental annotations
Fixes #859
1 parent a6ec1ce commit bc3ce4b

File tree

3 files changed

+116
-1
lines changed

3 files changed

+116
-1
lines changed

‎README.md

+1
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,7 @@ GlobalScope.launch {
5656
* [Guide to kotlinx.coroutines by example](docs/coroutines-guide.md) (**read it first**)
5757
* [Guide to UI programming with coroutines](ui/coroutines-guide-ui.md)
5858
* [Guide to reactive streams with coroutines](reactive/coroutines-guide-reactive.md)
59+
* [Compatibility policy and experimental annotations](docs/compatibility.md)
5960
* [Change log for kotlinx.coroutines](CHANGES.md)
6061
* [Coroutines design document (KEEP)](https://github.com/Kotlin/KEEP/blob/master/proposals/coroutines.md)
6162
* [Full kotlinx.coroutines API reference](http://kotlin.github.io/kotlinx.coroutines)

‎core/kotlinx-coroutines-debug/README.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -126,6 +126,6 @@ Do not use this module in production environment and do not rely on the format o
126126
[DebugProbes.install]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-debug/kotlinx.coroutines.debug/-debug-probes/install.html
127127
[DebugProbes.dumpCoroutines]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-debug/kotlinx.coroutines.debug/-debug-probes/dump-coroutines.html
128128
[DebugProbes.dumpCoroutinesState]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-debug/kotlinx.coroutines.debug/-debug-probes/dump-coroutines-state.html
129-
[DebugProbes.printScope]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-debug/kotlinx.coroutines.debug/-debug-probes/print-scope.html
130129
[DebugProbes.printJob]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-debug/kotlinx.coroutines.debug/-debug-probes/print-job.html
130+
[DebugProbes.printScope]: https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-debug/kotlinx.coroutines.debug/-debug-probes/print-scope.html
131131
<!--- END -->

‎docs/compatibility.md

+114
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
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 sill are leaving
68+
this option in case of unforeseen problems such as security problems.
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+
<!--- END -->

0 commit comments

Comments
 (0)