Skip to content

Commit fbf59d2

Browse files
qwwdfsadqwwdfsad
committed
Update documentation
1 parent 4a9fad5 commit fbf59d2

File tree

6 files changed

+241
-12
lines changed

6 files changed

+241
-12
lines changed

‎CHANGELOG.md

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,129 @@
1+
1.0.0-RC / 2020-08-17
2+
==================
3+
4+
Release candidate for 1.0.0 version. The goal of RC release is to collect feedback from users
5+
and provide 1.0.0 release with bug fixes and improvements based on that feedback.
6+
7+
While working on 1.0.0 version, we carefully examined every public API declaration of the library and
8+
split it to stable API, that we promise to be source and binary-compatible,
9+
and experimental API, that may be changed in the future.
10+
Experimental API is annotated with `@ExperimentalSerializationApi` annotation, which requires opt-in.
11+
For a more detailed description of the guarantees, please refer to the [compatibility guide](docs/compatibility.md).
12+
13+
The id of the core artifact with `@Serializable` annotation and `Json` format was changed
14+
from `kotlinx-serialization-runtime` to `kotlinx-serialization-core` to be more clear and aligned with other kotlinx libraries.
15+
16+
A significant part of the public API was renamed or extracted to a separate package.
17+
To migrate from the previous versions of the library, please refer to the [migration guide](docs/migration.md).
18+
19+
### API changes
20+
21+
#### Json
22+
23+
* Core API changes
24+
* `stringify` and `parse` are renamed to `encodeToString` and `decodeToString`
25+
* `parseJson` and `fromJson` are renamed to `parseJsonElement` and `decodeFromJsonElement`
26+
* Reified versions of methods are extracted to extensions
27+
28+
* `Json` constructor is replaced with `Json {}` builder function, `JsonConfiguration` is deprecated in favor
29+
of `Json {}` builder
30+
* All default `Json` implementations are removed
31+
* `Json` companion object extends `Json`
32+
33+
* Json configuration
34+
* `prettyPrintIndent` allows only whitespaces
35+
* `serializeSpecialFloatingPointValues` is renamed to `allowSpecialFloatingPointValues`. It now affects both serialization and deserialization behaviour
36+
* `unquoted` JSON flag is deprecated for removal
37+
* New `coerceInputValues` option for null-defaults and unknown enums (#90, #246)
38+
39+
* Simplification of `JsonElement` API
40+
* Redundant members of `JsonElement` API are deprecated or extracted to extensions
41+
* Potential error-prone API is removed
42+
* `JsonLiteral` is deprecated in favor of `JsonPrimitive` constructors with nullable parameter
43+
44+
* `JsonElement` builders rework to be aligned with stdlib collection builders (#418, #627)
45+
* Deprecated infix `to` and unaryPlus in JSON DSL in favor of `put`/`add` functions
46+
* `jsonObject {}` and `json {}` builders are renamed to `buildJsonObject {}` and `buildJsonArray {}`
47+
* Make all builders `inline` (#703)
48+
49+
* JavaScript support
50+
* `DynamicObjectParser` is deprecated in the favor of `Json.decodeFromDynamic` extension functions
51+
* `Json.encodeToDynamic` extension is added as a counterpart to `Json.decodeFromDynamic` (former `DynamicObjectParser`) (#116)
52+
53+
* Other API changes:
54+
* `JsonInput` and `JsonOutput` are renamed to `JsonEncoder` and `JsonDecoder`
55+
* Methods in `JsonTransformingSerializer` are renamed to `transformSerialize` and `transformDeserialize`
56+
* `JsonParametricSerializer` is renamed to `JsonContentPolymorphicSerializer`
57+
* `JsonEncodingException` and `JsonDecodingException` are made internal
58+
59+
* Bug fixes
60+
* `IllegalStateException` when `null` occurs in JSON input in the place of an expected non-null object (#816)
61+
* java.util.NoSuchElementException when deserializing twice from the same JsonElement (#807)
62+
63+
#### Core API for format authoring
64+
65+
* The new naming scheme for `SerialFormats`
66+
* Core functions in `StringFormat` and `BinaryFormat` are renamed and now follow the same naming scheme
67+
* `stringify`/`parse` are renamed to `encodeToString`/`decodeToString`
68+
* `encodeToByteArray`/`encodeToHexString`/`decodeFromByteArray`/`decodeFromHexString` in `BinaryFormat` are introduced instead of `dump`/`dumps`/`load`/`loads`
69+
70+
* New format instances building convention
71+
* Constructors replaced with builder-function with the same name to have the ability to add new configuration parameters,
72+
while preserving both source and binary compatibility
73+
* Format's companion objects now extend format class and can be used interchangeably
74+
75+
* SerialDescriptor-related API
76+
* `SerialDescriptor` and `SerialKind` are moved to a separate `kotlinx.serialization.descriptors` package
77+
* `ENUM` and `CONTEXTUAL` kinds now extend `SerialKind` directly
78+
* `PrimitiveDescriptor` is renamed to `PrimitiveSerialDescriptor`
79+
* Provide specific `buildClassSerialDescriptor` to use with classes' custom serializers, creating other kinds is considered experimental for now
80+
* Replace extensions that returned lists (e.g. `elementDescriptors`) with properties that return iterable as an optimization
81+
* `IndexOutOfBoundsException` in `descriptor.getElementDescriptor(index)` for `List` after upgrade to 0.20.0 is fixed (#739)
82+
83+
* SerializersModule-related API
84+
* `SerialModule` is renamed to `SerializersModule`
85+
* `SerialModuleCollector` is renamed to `SerializersModuleCollector`
86+
* All builders renamed to be aligned with a single naming scheme (e.g. `SerializersModule {}` DSL)
87+
* Deprecate infix `with` in polymorphic builder in favor of subclass()
88+
* Helper-like API is extracted to extension functions where possible.
89+
* `polymorphicDefault` API for cases when type discriminator is not registered or absent (#902)
90+
91+
* Contextual serialization
92+
* `@ContextualSerialization` is split into two annotations: `@Contextual` to use on properties and `@UseContextualSerialization` to use on file
93+
* New `SerialDescriptor.capturedKClass` API to introspect SerializersModule-based contextual and polymorphic kinds (#515, #595)
94+
95+
* Encoding-related API
96+
* Encoding-related classes (`Encoder`, `Decoder`, `AbstractEncoder`, `AbstractDecoder`) are moved to a separate `kotlinx.serialization.encoding` package
97+
* Deprecated `typeParameters` argument in `beginStructure`/`beginCollectio`n methods
98+
* Deprecated `updateSerializableValue` and similar methods and `UpdateMode` enum
99+
* Renamed `READ_DONE` to `DECODE_DONE`
100+
* Make extensions `inline` where applicable
101+
* `kotlinx.io` mockery (`InputStream`, `ByteArrayInput`, etc) is removed
102+
103+
* Serializer-related API
104+
* `UnitSerializer` is replaced with `Unit.serializer()`
105+
* All methods for serializers retrieval are renamed to `serializer`
106+
* Context is used as a fallback in `serializer` by KType/Java's Reflect Type functions (#902, #903)
107+
* Deprecated all exceptions except `SerializationException`.
108+
* `@ImplicitReflectionSerializer` is deprecated
109+
* Support of custom serializers for nullable types is added (#824)
110+
111+
#### ProtoBuf
112+
113+
* `ProtoBuf` constructor is replaced with `ProtoBuf {}` builder function
114+
* `ProtoBuf` companion object now extends `ProtoBuf`
115+
* `ProtoId` is renamed to `ProtoNumber`, `ProtoNumberType` to `ProtoIntegerType` to be consistent with ProtoBuf specification
116+
* ProtoBuf performance is significantly (from 2 to 10 times) improved (#216)
117+
* Top-level primitives, classes and objects are supported in ProtoBuf as length-prefixed tagless messages (#93)
118+
* `SerializationException` is thrown instead of `IllegalStateException` on incorrect input (#870)
119+
* `ProtobufDecodingException` is made internal
120+
121+
#### Other formats
122+
* All format constructors are migrated to builder scheme
123+
* Properties serialize and deserialize enums as strings (#818)
124+
* CBOR major type 2 (byte string) support (#842)
125+
* `ConfigParser` is renamed to `Hocon`, `kotlinx-serialization-runtime-configparser` artifact is renamed to `kotlinx-serialization-hocon`
126+
* Do not write/read size of collection into Properties' map (#743)
1127

2128
0.20.0 / 2020-03-04
3129
==================

‎README.md

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,7 @@ fun main() {
4646
println(string) // {"name":"kotlinx.serialization","language":"Kotlin"}
4747
// Deserializing back into objects
4848
val obj = Json.decodeFromString<Project>(string)
49-
println(obj) // Project(name=kotlinx.serialization, langauge=Kotlin)
49+
println(obj) // Project(name=kotlinx.serialization, language=Kotlin)
5050
}
5151
```
5252

@@ -196,8 +196,7 @@ commonMain {
196196
}
197197
}
198198
```
199-
Additionally, artifacts with `-js` and `-native` suffixes are available to directly depend
200-
on platform specific artifact.
199+
The same artifact coordinates can be used to depend on platform-specific artifact in platform-specific source-set.
201200

202201
### Maven/JVM
203202

‎docs/compatibility.md

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
# Compatibility policy
2+
3+
This document describes the compatibility policy of kotlinx.serialization library since version 1.0.0 and Kotlin 1.4.0.
4+
5+
Note that content of this document is applicable only for JVM platform,
6+
since Kotlin/Native and Kotlin/JS are experimental themselves and currently do not impose any backward-compatibility guarantees.
7+
8+
- [Core library compatibility](#core-library-compatibility)
9+
* [General (Stable) API](#general-stable-api)
10+
* [Experimental API](#experimental-api)
11+
* [Internal API](#internal-api)
12+
- [Compatibility with Kotlin compiler plugin](#compatibility-with-kotlin-compiler-plugin)
13+
14+
## Core library compatibility
15+
16+
Core library public API comes in three flavours: general (stable), experimental, and internal.
17+
ll public API except stable is marked with the corresponding annotation.
18+
To learn how to use declarations that require opt-in, please refer to [corresponding documentation page](https://kotlinlang.org/docs/reference/opt-in-requirements.html#non-propagating-use).
19+
20+
### Stable API
21+
22+
Stable API is guaranteed to preserve its ABI and documented semantics:
23+
24+
* It cannot change its semantics expressed in its documentation
25+
* It is binary backwards-compatible: during update of `kotlinx.serialization` version, previously compiled code will continue to work.
26+
For example, for a library that depends only on `kotlinx.serialization` stable API,
27+
clients of the library can easily depend on a next `kotlinx.serialization` version and expect everything to work.
28+
* It is source backwards compatible modulo major deprecation. Most of the API is here to stay forever,
29+
unless an unfixable security or design flaw is exposed. Minor releases never add source-incompatible changes to stable API
30+
31+
#### Deprecation cycle
32+
33+
When API is deprecated, it goes through multiple stages and there is at least one major release between each stages.
34+
35+
Feature is deprecated with compilation warning. Most of the time, proper replacement (and corresponding `replaceWith` declaration) is provided to automatically migrate deprecated usages with a help of IntelliJ IDEA.
36+
Deprecation level is increased to error or hidden. It is no longer possible to compile new code against deprecated API, though it is still present in the ABI.
37+
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 this option in case of unforeseen problems such as security issues.
38+
39+
40+
### Experimental API
41+
42+
This API marked as `@ExperimentalSerializationApi`. API is marked experimental when its design has potential open questions which may eventually lead to either semantics changes of the API or its deprecation.
43+
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. Otherwise, either semantics is fixed without changes in ABI or API goes through deprecation cycle.
44+
45+
However, we'll try to provide best-effort compatibility — such declarations won't be deleted or changed instantly,
46+
they will go through deprecation cycle if this is possible. However, these deprecation cycle may be faster than usual.
47+
48+
Usage notes:
49+
50+
* Experimental API can be used in your applications if maintenance cost is clear:
51+
additional migrations may have to be performed during `kotlinx.serialization` update.
52+
53+
* Experimental API can be used in other **experimental** API (for example, a custom serialization format).
54+
In such cases, clients of the API have to be aware about experimentality.
55+
56+
* It's not recommended to use it as a dependency in your **stable** API, even as an implementation detail.
57+
Due to the lack of binary backward compatibility, your clients may experience behavioural changes
58+
or runtime exceptions when an unexpected version of `kotlinx.serialization` gets included in the runtime classpath.
59+
60+
### Internal API
61+
62+
This API is marked with `@InternalSerializationApi` or located in `kotlinx.serialization.internal` package.
63+
It does not have any binary or source compatibility guarantees and can be deprecated or deleted without replacement at any time.
64+
65+
It is not recommended to use it.
66+
However, if you have a rare use-case that can be solved only with internal API, it is possible to use it.
67+
In such a case, please create an issue on GitHub in order for us to understand a use-case and to provide stable alternative.
68+
69+
## Compatibility with Kotlin compiler plugin
70+
71+
`kotlinx.serialization` also has the compiler plugin, that generates code depending on the core library.
72+
Therefore, the compiler plugin should be compatible with the runtime library to work.
73+
Kotlin & `kotlinx.serialization` plugin 1.4.0 are compatible with 1.0.0 runtime library.
74+
75+
For further updates, we have the following policy:
76+
77+
* New Kotlin compiler plugins should be backward compatible with core library.
78+
It means that it is possible to freely update Kotlin version in a project without changing the code
79+
and without the need to update `kotlinx.serialization` runtime.
80+
In other words, `1.0.0` runtime can be used with any of Kotlin `1.4.x` versions.
81+
82+
* New Kotlin compiler plugin features may require new `kotlinx.serialization` library.
83+
For example, if Kotlin `1.4.x` gets serialization of unsigned integers,
84+
it would require a corresponding runtime version higher than `1.0.0`.
85+
This would be indicated by a compiler error specific to a particular feature.
86+
87+
* New core library versions may or may not require Kotlin compiler plugin update,
88+
depending on a particular release.
89+
We'll try to avoid these situations; however, in case of some unexpected issues, it may be necessary.
90+
So it is possible to have a situation where upgrading serialization runtime from `1.x` to `1.y` requires an update of Kotlin version from `1.4.0` to `1.4.x`.
91+
The compiler can detect such problems and will inform you if its version is incompatible with a current version of core library.

‎docs/migration.md

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# Migration from 0.20.0 version to 1.0.0
2+
3+
For adopters of earlier versions of `kotlinx.serialization`, a dedicated migration path is prepared.
4+
During the preparation of serialization 1.0.0 release, most of the API has been changed, renamed, moved to
5+
a separate package or made internal. IDEA migrations were introduced, but unfortunately not all API can be migrated
6+
with automatic replacements.
7+
8+
To simplify your migrations path, it is recommended to enable star imports in IDE (so all extensions are imported automatically) first.
9+
10+
1. Update `kotlinx.serialization` to version 1.0.0-RC (this is the last version that has migrations for pre-1.0.0 versions)
11+
2. Rename dependency from `kotlinx-serialization-runtime` to `kotlinx-serialization-core`
12+
3. For multiplatform usages, remove dependencies to platform-specific artifacts (e.g. `kotlinx-serialization-runtime-js`), they are [no longer required](/README.md#multiplatform-common-js-native) by Gradle.
13+
4. Update Kotlin to 1.4.0
14+
5. Start applying replacements for the deprecated code
15+
6. If some signatures are not resolved, try to hit `alt + Enter` and import the signature
16+
7. If methods are still not resolved, it is recommended to use star imports for `kotlinx.serialization` signatures in the problematic file
17+
18+
For less trivial issues, it is recommended to study [the changelog](../CHANGELOG.md#100-rc--2020-08-17) or to ask for help in `#serialization` Slack channel.

‎formats/README.md

Lines changed: 3 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,13 @@
11
# Serialization formats
22

3-
This area of repository contains different libraries with various add-on formats which
4-
were not included in the main runtime library – because they are not so popular, or they're big,
5-
or they contain other JVM runtime dependencies.
3+
This area of repository contains different libraries with various add-on formats which
4+
were not included in the core library.
65

7-
For convenience, they have same groupId, versioning and release cycle as main runtime.
6+
For convenience, they have same `groupId`, versioning and release cycle as core library.
87

98
## HOCON
109

1110
* Artifact id: `kotlinx-serialization-hocon`
12-
* Since version: 0.4.1
1311
* Platform: JVM only
1412

1513
Allows deserialization of `Config` object from popular [lightbend/config](https://github.com/lightbend/config) library
@@ -19,21 +17,18 @@ You can learn about "Human-Optimized Config Object Notation" or HOCON from libra
1917
## ProtoBuf
2018

2119
* Artifact id: `kotlinx-serialization-protobuf`
22-
* Since version: 0.20.0
2320
* Platform: all supported platforms
2421
* Status: experimental
2522

2623
## CBOR
2724

2825
* Artifact id: `kotlinx-serialization-cbor`
29-
* Since version: 0.20.0
3026
* Platform: all supported platforms
3127
* Status: experimental
3228

3329
## Properties
3430

3531
* Artifact id: `kotlinx-serialization-properties`
36-
* Since version: 0.20.0
3732
* Platform: all supported platforms
3833
* Status: experimental
3934

‎guide/example/example-readme-01.kt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,5 +14,5 @@ fun main() {
1414
println(string) // {"name":"kotlinx.serialization","language":"Kotlin"}
1515
// Deserializing back into objects
1616
val obj = Json.decodeFromString<Project>(string)
17-
println(obj) // Project(name=kotlinx.serialization, langauge=Kotlin)
17+
println(obj) // Project(name=kotlinx.serialization, language=Kotlin)
1818
}

0 commit comments

Comments
 (0)