Add a document describing how to migrate a project to BCV 0.15.0

Author: fzhinkin

docs/design/0.15.0-migration-guide.md

@@ -0,0 +1,94 @@
+The major feature shipped with the release 0.15.0 of the Binary Compatibility Validator is Kotlin libraries (or KLibs) 
+ABI validation support.
+
+This support, however, comes with a few changes that break the plugin's compatibility:
+- ABI file names (`api/<project name>.api`) are no longer treated in a case-insensitive way;
+- Gradle tasks provided by the plugin changed their API.
+
+If you neither configure BCV Gradle tasks manually nor have an ABI file with a name in a case different
+from how the project was named in the settings, these changes won't affect you.
+
+Otherwise, the steps required for smooth migration are described below.
+
+### ABI file names are no longer treated in a case-insensitive way
+
+Starting from the version `0.15.0`, name of an ABI dump file stored in the project's directory
+has to match project's name. Previously, a project named `gradle-project` might use an ABI file
+named `Gradle-Project.api`, but now it has to be `gradle-project.api`.
+
+On case-insensitive filesystems (Windows and macOS filesystems are case-insensitive) the change won't manifest itself,
+but on case-sensitive filesystems (Linux filesystems) the validation will start failing due to a missing ABI dump file
+error.
+
+You can either rename the existing file or delete it and run `apiDump` task.  
+
+If you're using git SCV, it's highly recommended to use `git mv` command to rename a file, or a pair of `git rm` and 
+`git add` commands, if you're deleting the old file and then generating a new one. When done differently, git may
+not reflect changes in a repository index (it's specific to case-insensitive filesystems).
+
+If you're using another SCV, please consult its documentation for details on how to deal with file renaming on
+case-insensitive filesystems.
+
+### Gradle tasks provided by the plugin changed their API
+
+All Gradle tasks that existed before are still presented and in use, but some of them changed
+their API to use Gradle Properties-based configuration. There are several advantages of using Gradle Property
+instead of regular Kotlin properties, but the main one is that it improves dependency tracking between tasks.
+You can [Gradle docs](https://docs.gradle.org/current/userguide/lazy_configuration.html) for more details
+on the subject.
+
+The following task-classes changed their API:
+- KotlinApiBuildTask
+    - `ignoredPackages`, `nonPublicMarkers`, `ignoredClasses`, `publicPackages`, `publicMarkers`, `publicClasses` are
+  all `SetProperty<String>` instances now;
+    - `outputApiDir` was renamed to `outputApiFile` and became `RegularFileProperty` instance; now it should point to 
+  the generated file instead of a directory holding it;
+    - `inputClassesDirs` and `inputDependencies` are both `ConfigurableFileCollection` instances now.
+- KotlinApiCompareTask
+    - `projectApiFile` and `generatedApiFile` are both `RegularFileProperty` instances now.
+
+If you were configuring `KotlinApiBuildTask.outputApiDir`, `KotlinApiCompareTask.projectApiFile` or
+`KotlinApiCompareTask.generatedApiFile` by assigning a file instance to it, now these properties could only 
+be configured by using [RegularFileProperty setters](https://docs.gradle.org/current/javadoc/org/gradle/api/file/RegularFileProperty.html).
+
+Value assignments to `KotlinApiBuildTask.inputClassesDirs` and `KotlinApiBuildTask.inputDependencies` properties have 
+to be replaced with [ConfigurableFileCollection setters](https://docs.gradle.org/current/javadoc/org/gradle/api/file/ConfigurableFileCollection.html).
+
+All `KotlinApiBuildTask`'s filters could be configured by using [SetProperty setters](https://docs.gradle.org/current/javadoc/org/gradle/api/provider/SetProperty.html)
+now.
+
+Below is an example of how task configuration needs to be updated:
+```kotlin
+// Old configuration
+val buildTask = tasks.register("buildApi", KotlinApiBuildTask::class.java) {
+  val classes = compilation.output.classesDirs
+
+  it.inputClassesDirs = files(classes)
+  it.inputDependencies = files(classes)
+  it.outputApiDir = project.layout.buildDirectory.get().asFile
+  it.ignoredPackages = setOf("org.example")
+}
+
+val checkTask = tasks.register("checkApi", KotlinApiCompareTask::class.java) {
+  it.projectApiFile = project.layout.projectDirectory.dir("api").file("gradle-project.api").asFile
+  it.generatedApiFile = project.layout.buildDirectory.get().asFile.resolve("dump.api")
+  
+  it.dependsOn(buildTask)
+}
+```
+
+```kotlin
+// New configuration
+val buildTask = tasks.register("buildApi", KotlinApiBuildTask::class.java) {
+  val classes = compilation.output.classesDirs
+
+  it.inputClassesDirs.from(classes)
+  it.inputDependencies.from(classes)
+  it.outputApiFile.set(project.layout.buildDirectory.map { it.file("gradle-project.api") })
+  it.ignoredPackages.set(setOf("org.example"))
+}
+val checkTask = tasks.register("checkApi", KotlinApiCompareTask::class.java) {
+  it.projectApiFile.set(project.layout.projectDirectory.dir("api").file("gradle-project.api"))
+  it.generatedApiFile.set(buildTask.flatMap { it.outputApiFile })
+}
+```