From dd51485858d03d5f99e9c180ab0674a3deacab8e Mon Sep 17 00:00:00 2001 From: "Sergey.Shanshin" Date: Mon, 10 Jun 2024 13:47:07 +0200 Subject: [PATCH] Removed migrations --- .../migrations/migration-to-0.8.0.md | 583 ------------------ 1 file changed, 583 deletions(-) delete mode 100644 docs/gradle-plugin/migrations/migration-to-0.8.0.md diff --git a/docs/gradle-plugin/migrations/migration-to-0.8.0.md b/docs/gradle-plugin/migrations/migration-to-0.8.0.md deleted file mode 100644 index d178446b..00000000 --- a/docs/gradle-plugin/migrations/migration-to-0.8.0.md +++ /dev/null @@ -1,583 +0,0 @@ -# Kover migration guide from 0.7.x to 0.8.0 - -- [Migration steps](#migration-steps) -- [Conceptual changes](#conceptual-changes) - - [Single kover project extension](#single-kover-project-extension) - - [The concept of default reports has been removed](#the-concept-of-default-reports-has-been-removed) - - [Total reports](#total-reports) - - [Custom reports variants](#custom-reports-variants) - - [More about the reports variant](#more-about-the-reports-variant) - - [The format-specific reports filters has been removed](#the-format-specific-reports-filters-has-been-removed) - - [Added the ability of lazy configuration](#added-the-ability-of-lazy-configuration) - - [Added public interfaces for Kover tasks](#added-public-interfaces-for-kover-tasks) -- [Migration error messages](#migration-error-messages) - - -## Migration steps -1. Move all content of extension `koverReport` to `kover { reports { ... } }`. -If you use the extensions property to access the extension - ```kotlin - extensions.configure("koverReport") { - // content - } - ``` - then it is necessary to move all its contents to - ```kotlin - extensions.configure("kover") { - reports { - // content - } - } - ``` -2. Move the default reports settings to the total report settings. - Instead of - ```kotlin - koverReport { - defaults { - // content - } - } - ``` - write - ```kotlin - kover { - reports { - total { - // content - } - } - } - ``` -3. For Android Projects or Kotlin Multiplatform with Android target: - If you use merging of Android build variants, you need to create a custom variant, configure it, and then you can generate reports for this variant. - - Instead of - ```kotlin - koverReport { - defaults { - mergeWith(/*dependent project*/) - // reports settings - } - } - ``` - write - ```kotlin - kover { - currentProject { - createVariant("custom") { - addWithDependencies(/*dependent project*/) - } - } - reports { - variant("custom") { - // reports settings - } - } - } - ``` - See details in [corresponding section](#custom-reports-variants). -4. Delete all `filters` blocks from the settings of a specific report (XML, HTML, verify, log, etc.), e.g. - ```kotlin - koverReport { - defaults { - html { - filters { - // filters - } - } - } - } - ``` - move the filters to common block for all variants settings - ```kotlin - kover { - reports { - filters { - // filters - } - } - } - ``` - or specific variant settings, like - ```kotlin - kover { - reports { - total { - filters { - // filters - } - } - } - } - ``` - If you need to create specific reports with individual sets of filters, then create a [custom reports variant](#custom-reports-variants). - -5. Rename some functions and properties, the actual names are written in error messages or IDE hints -6. For kts files and Gradle versions less than 8.2, it is necessary to replace the assignment operator with a call `set()` function for some properties in DSL. - These properties can be found by configuration error messages. - - An example of such properties: `minValue` and `maxValue` in the bound of the verification rule. - - -## Conceptual changes -### Single kover project extension -The `0.7.x` version used two project extensions named `kover` and `koverReports`. -This was confusing and made it difficult to search through documentation or examples. - -Since `0.8.0`, there is only one `kover` extension left. -All the settings that used to be in `koverReports` are now located in -```kotlin -kover { - reports { - // setting from old koverReports extension - } -} -``` -The settings from the old `kover` are now either left as is, or moved to `kover { currentProject { ... } }` block. - -Following configuration -```kotlin -kover { - // exclude classes compiled by Java compiler from all reports - excludeJavaCode() - - excludeTests { - // exclude Gradle test tasks - tasks(testTasks) - } - excludeInstrumentation { - // exclude classes from instrumentation - classes(unistrumentedClasses) - } - excludeSourceSets { - // exclude source classes of specified source sets from all reports - names(excludedSourceSet) - } -} -``` - -Since `0.8.0` looks like: -```kotlin -kover { - currentProject { - instrumentation { - /* exclude Gradle test tasks */ - disabledForTestTasks.addAll(testTasks) - } - - instrumentation { - // exclude classes from instrumentation - excludedClasses.addAll(unistrumentedClasses) - } - - sources { - // exclude classes compiled by Java compiler from all reports - excludeJava = true - - // exclude source classes of specified source sets from all reports - excludedSourceSets.addAll(excludedSourceSet) - } - } -} -``` - -### The concept of default reports has been removed -In the `0.7.x` version, there were tasks named `koverHtmlReport`, `koverXmlReport`, `koverVerify`, `koverLog`, `koverBinaryReport`, -which included only classes and tests for JVM target, and it was also possible to add tests from classes of specified Android build variant using -```kotlin -koverReport { - defaults { - mergeWith("buildVariant") - } -} -``` - -Starting with the `0.8.0` version, these features have been removed. -However, to implement similar capabilities, the concepts of _Total reports_ and _Custom reports_ were introduced. - -### Total reports -Since `0.8.0` tasks `koverHtmlReport`, `koverXmlReport`, `koverVerify`, `koverLog`, `koverBinaryReport` are designed -to generate reports on all classes and tests of the project. -For JVM projects, nothing changes compared to the `0.7.x` version, however, for Android projects, -running one of these tasks will result running tests for all build variants present in the project. - -### Custom reports variants -In the `0.7.x` version, it was allowed to merge a report for several Android build variants only into default reports, -it was not possible to create several combinations with the arbitrary inclusion of different build variants. - -Since `0.8.0` in order to merge several Android build variants, you need to create a custom reports variant. - -The newly created variant is initially empty, in order for classes to appear in the report and tests to be executed -when generating it, need to add existing variants provided from Kotlin targets to it: it can be a `jvm` variant, or any of an Android build variant. -```kotlin -kover { - currentProject { - createVariant("custom") { - add("jvm") - add("release") - } - } -} -``` - -Creating a variant with a name `custom` will add tasks named `koverHtmlReportCustom`, `koverXmlReportCustom`, `koverVerifyCustom`, `koverLogCustom`, `koverBinaryReportCustom`. - -### More about the reports variant -A reports variant is a set of information used to generate a report, namely: -project classes, a list of Gradle test tasks, classes that need to be excluded from instrumentation. - -There are several types of report variants: -- total variant (have no special name), always created -- variant for classes in JVM target (named `jvm`), created by Kover Gradle Plugin if JVM target is present -- variants for the Android build variant (the name matches the name of the build variant), created by Kover Gradle Plugin if there are Android build variants in the project -- custom variants (the name is specified when creating), declared in the build script configuration - -For each variant, a set of tasks is created in the project to generate reports on the information contained in it. - -The names are generated according to the following rule: -`koverHtmlReport`, `koverXmlReport`, `koverVerify`, `koverLog`, `koverBinaryReport` - - -The reports variant can be used in another project to create a merged reports. -To do this, in another project, which we will call the merging project, we will specify a dependency on the project from which we want to import classes and Gradle test tasks. -```kotlin -dependencies { - kover(project(":lib")) -} -``` -As a result, if you run the `:koverHtmlReport` task, it will run all the tests from merging project and `:lib` project -and generate a report for all classes from merging project and `:lib` project. - -However, if you call a task for a named variant, for example `:koverHtmlReportRelease`, then it will run tests for `release` variant from merging project and `:lib` project -and generate a report for classes of `release` variant from merging project and `:lib` project. - -At the same time, it is recommended that variant `release` is also present in the `:lib` project, however, -for technical reasons, such a check may not be implemented in `0.8.0` and subsequent versions. - -### The format-specific reports filters has been removed -Previously, it was acceptable to override filters for each report format (XML, HTML, etc.), like -```kotlin -koverReport { - filters { - // top-level filters - } - defaults { - filters { - // filters for all default reports - } - - html { - filters { - // filters for HTML default report - } - } - } -} -``` - -This is very confusing, because there are 3 levels in which you can write `filters { }` also it is difficult for users to understand exactly where to write filters - which leads to the fact of copy-paste the same filters are specified for all types of reports (inside xml, html, verify blocks). - -Since `0.8.0`, specifying filters for specific type of report (HTML or XML) is deprecated. It is now possible to create custom variants of reports, if it is necessary to generate a report with a different set of filters. -In this case, it is better to create a new custom variant and override the filters in it: -```kotlin -kover { - currentProject { - createVariant("customJvm") { - add("jvm") - } - } - - reports { - variant("customJvm") { - filters { - // filters only for customJvm report set - } - } - } -} - -``` - - -### Added the ability of lazy configuration -In some cases, the values are not known at the time of configuration, for example, when using convention plugins and extensions in them. - -To do this, overloads have been added that allow to work with the value providers (Gradle `Provider` type). - -```kotlin -kover { - reports { - filters { - exludes { - classes(classProvider) - } - } - - verify { - rule { - bound { - minValue = minValueProvider - } - // or - minBound(minValueProvider) - } - } - } -} - -``` - - -### Added public interfaces for Kover tasks - -Now all Kover report tasks implement interface `kotlinx.kover.gradle.plugin.dsl.tasks.KoverReport`. - -Also, a separate interface has been created for each report type: - - `kotlinx.kover.gradle.plugin.dsl.tasks.KoverXmlReport` - - `kotlinx.kover.gradle.plugin.dsl.tasks.KoverHtmlReport` - - `kotlinx.kover.gradle.plugin.dsl.tasks.KoverLogReport` - - `kotlinx.kover.gradle.plugin.dsl.tasks.KoverVerifyReport` - - `kotlinx.kover.gradle.plugin.dsl.tasks.KoverBinaryReport` - -Adding public interfaces will allow to filter Kover tasks, for example, to specify them in dependencies -```kotlin -tasks.check { - dependsOn(tasks.matching { it is KoverHtmlReport }) -} -``` - -## Migration error messages - -#### Unresolved reference: koverReport -Solution: -Move content of `koverReport` extension to -```kotlin -kover { - reports { - // place content of `koverReport` here - } -} -``` - -#### Unresolved reference: KoverReportExtension -There is no such extension anymore. - -If used configuration like -```kotlin -extensions.configure("koverReport") { - // content -} -``` -then it is necessary to move all its contents to -```kotlin -extensions.configure("kover") { - reports { - // content - } -} -``` - -#### Default reports was removed, the concepts of total and custom reports are now used. -If you have an Kotlin/JVM project or an Kotlin Multiplatform project without an Android target, then block `total` should be used instead. - -Was: -```kotlin -koverReport { - defaults { - // content - } -} -``` -become: -```kotlin -kover { - reports { - total { - // content - } - } -} -``` - -#### Kover renaming: Symbol ... was removed, use ... instead -The function or property used has been renamed. Replace the usage with the character specified in the message. - -#### Function excludeJavaCode was removed, to exclude all Java sources write here `variants { sources { excludeJava = true } }` or `variants { sources { excludeJava.set(true) } } instead. - -Instead of -```kotlin -kover { - excludeJavaCode() -} -``` -use for Gradle > 8.2 -```kotlin -kover { - variants { - sources { - excludeJava = true - } - } -} -``` -and for Gradle <= 8.2 -```kotlin -kover { - variants { - sources { - excludeJava.set(true) - } - } -} -``` - -#### Function excludeTests was removed, specify excluded tasks in `currentProject { instrumentation { disabledForTestTasks.addAll(/*name of tasks*/) } }` - -Instead of -```kotlin -kover { - excludeTests { - tasks(/*names*/) - } -} -``` -write -```kotlin -kover { - currentProject { - instrumentation { - disabledForTestTasks.addAll(/*names*/) - } - } -} -``` - -#### Function excludeInstrumentation was removed, specify instrumentation excluded classes in `currentProject { instrumentation { excludedClasses.addAll(/*class names*/) }` - -Instead of -```kotlin -kover { - excludeInstrumentation { - classes(/* class names */) - } -} -``` -write -```kotlin -kover { - currentProject { - instrumentation { - excludedClasses.addAll(/* class names */) - } - } -} -``` - -#### "Function excludeSourceSets was removed, specify instrumentation excluded classes in `currentProject { sources { excludedSourceSets.addAll(/*source sets names*/) } }` - -Instead of -```kotlin -kover { - excludeSourceSets { - names(/*source sets names*/) - } -} -``` - -write -```kotlin -kover { - currentProject { - sources { - excludedSourceSets.addAll(/*source sets names*/) - } - } -} -``` - -#### Block mergeWith was removed, create custom reports variant and merge with specified variant - -Now it is possible to add provided variant only to custom reports variant. - -You need to create a custom variant, configure it, and then you can generate reports for this variant. - -Instead of -```kotlin -koverReport { - defaults { - mergeWith(/*dependent project*/) - } -} -``` -write -```kotlin -kover { - currentProject { - createVariant("custom") { - addWithDependencies(/*dependent project*/) - } - } -} -``` -See details in [corresponding section](#custom-reports-variants). - -#### Val cannot be reassigned -or -#### Type mismatch: inferred type is ... but Property<...> was expected -or -#### The integer literal does not conform to the expected type Property -Reason: the kts file is used in Gradle version less than 8.2 - -Solution: Update Gradle version or write `.set(value)` instead of ` = value` - -#### It is forbidden to override filters for a specific report, use custom report variants to create reports with a different set of filters -It is necessary to delete the `filters` block from the settings of a specific report (XML, HTML, verify, log, etc.). -```kotlin -koverReport { - defaults { - html { - filters { - // filters - } - } - } -} -``` -move the filters to common block for all variants settings -```kotlin -kover { - reports { - filters { - // filters - } - } -} -``` -or specific variant settings -```kotlin -kover { - reports { - total { - filters { - // filters - } - } - } -} -``` -If you need to create specific reports with individual sets of filters, then create a [custom reports variant](#custom-reports-variants). - -#### Property isEnabled was renamed to disabled and inverted -Now to disable the rule you need to use the `disabled` property. -```kotlin -kover { - reports { - verify { - rule { - disabled = true - // or disabled.set(true) for kts files in Gradle < 8.2 - } - } - } -} -```