From aff5b91da36567d27c4596535d50ea310e7be739 Mon Sep 17 00:00:00 2001 From: Leonid Startsev Date: Mon, 4 Dec 2023 17:26:06 +0100 Subject: [PATCH] Provide changelog and migration guide for kotlinx-metadata-jvm 0.8.0 --- libraries/kotlinx-metadata/jvm/ChangeLog.md | 13 +++++++ libraries/kotlinx-metadata/jvm/Migration.md | 39 ++++++++++++++++++++- 2 files changed, 51 insertions(+), 1 deletion(-) diff --git a/libraries/kotlinx-metadata/jvm/ChangeLog.md b/libraries/kotlinx-metadata/jvm/ChangeLog.md index f9aabbb2f66..4d90b71d0c2 100644 --- a/libraries/kotlinx-metadata/jvm/ChangeLog.md +++ b/libraries/kotlinx-metadata/jvm/ChangeLog.md @@ -1,5 +1,18 @@ # kotlinx-metadata-jvm +## 0.8.0 + +This release concludes our API overhaul: it features last significant API changes, as well as raised deprecations to ERROR level almost everywhere. +To help with migration, we've prepared a special [guide](Migration.md#migrating-from-070-to-080). +It still uses Kotlin 1.9, but is able to read or write metadata of version 2.0. + +- Provide a separate class for representing metadata version in kotlinx-metadata: `JvmMetadataVersion` +- Unify write() method and make it a member of `KotlinClassMetadata` (also `KotlinModuleMetadata`) +- Split `KotlinClassMetadata.read` into `readStrict` and `readLenient` +- Promote most deprecations in kotlinx-metadata-jvm to ERROR, including Flags API and Visitors API. +- Deprecate `KmProperty.hasGetter(hasSetter)` in favor of `KmProperty.getter(setter)` +- Add missing delegation in `KmDeclarationContainerVisitor.visitExtensions` for consistency + ## 0.7.0 This release features several significant API changes. To help with migration, we've prepared a special [guide](Migration.md#migrating-from-06x-to-070). diff --git a/libraries/kotlinx-metadata/jvm/Migration.md b/libraries/kotlinx-metadata/jvm/Migration.md index 71dd5dea1ba..b4c3418c848 100644 --- a/libraries/kotlinx-metadata/jvm/Migration.md +++ b/libraries/kotlinx-metadata/jvm/Migration.md @@ -3,6 +3,43 @@ Starting with 0.6.0 release, Kotlin team is focused on revisiting and improving kotlinx-metadata-jvm API, with an aim to provide a stable release in the near future. As a result, the API was reshaped, with cuts here and there, so we've provided a migration guide to help you with updates. +## Migrating from 0.7.0 to 0.8.0 + +### Choosing between read methods + +In 0.8.0, a standard entry point, `KotlinClassMetadata.read()`, is deprecated. Instead, we offer two new methods that take same instance +of `Metadata`: `KotlinClassMetadata.readLenient()` and `KotlinClassMetadata.readStrict()`. +You have to choose which method better suites your application needs. +In short, `readStrict()` is fully equivalent to old `read()`. `readLenient()` allows you to read potentially incompatible metadata, but +doesn't allow you to write anything afterward. +You can read more about the differences in the [readme](ReadMe.md#working-with-different-versions). +Detailed description of the problem being solved is presented [in this ticket](https://youtrack.jetbrains.com/issue/KT-59441). + +### Replacement for IntArray as a metadata version + +Historically, a metadata version in kotlinx-metadata-jvm API was represented as `IntArray` (because this is how it is stored in the `Metadata` annotation). +However, having a general-purpose array for storing versions is not very handy: making comparisons or simply converting to string is notoriously inconvenient for arrays. +Therefore, we decided to replace `IntArray` with a new specialized type, `JvmMetadataVersion`. +It carries the same three components: `major`, `minor`, and `patch` (with possibility to add new in the future) and provides convenient `equals`, `compareTo`, `toString`, and other methods. +`KotlinClassMetadata.version` (described below) is exposed as a value of this type. +Main migration path here is to replace `KotlinClassMetadata.COMPATIBLE_METADATA_VERSION` with new value with the same meaning: `JvmMetadataVersion.LATEST_STABLE_SUPPORTED`. + +### Write is now a member method + +Previously, the way to write some metadata were companion methods like `KotlinClassMetadata.writeClass()`, etc. +It was not very convenient: +- Function names are different and don't look nice if you use them in e.g., `when`. +- It is easy to forget `metadataVersion` or `flags` parameter since they are not present in `KmClass` and have default values. + +To mitigate these problems, we have changed the API in a way that version and flags are always stored in the corresponding `KotlinClassMetadata` instance. +You can access and change them with `kotlinClassMetadata.version` and `kotlinClassMetadata.flag` properties. +Consequently, there is no need for companion object methods anymore, as we have all information required in the instance. +To write the metadata and get `Metadata` annotation, simply call `kotlinClassMetadata.write()` without arguments. + +Note: we strongly recommend doing it at the same instance you received from `KotlinClassMetadata.read()` instead of creating a new one. +It would be easier not to forget the correct version that way. +See usage example in [this readme section](ReadMe.md#transforming-metadata). + ## Migrating from 0.6.x to 0.7.0 ### Migration from Flags API to Attributes API @@ -172,7 +209,7 @@ a [helper function](https://github.com/JetBrains/kotlin/blob/3d679b76bce04a9bfbb or by [directly calling the annotation constructor](https://kotlinlang.org/docs/annotations.html#instantiation). > Note: as annotation instantiation is not available for Java clients, `KotlinClassHeader` is still present and reserved for construction from Java. -It implements `kotlin.Metadata` annotation interface, so they can be used interchangeably. +> It implements `kotlin.Metadata` annotation interface, so they can be used interchangeably. Additionally, the property `KotlinClassMetadata.header: KotlinClassHeader` was changed into `KotlinClassMetadata.annotationData: Metadata`, so it is also possible to use `Metadata` directly to write metadata back (see example in the section below).