Add docs for migrating booster from v4 to v5

johnsonlee · Jul 21, 2024 · 3d2202f · 3d2202f
1 parent 507b637
commit 3d2202f
Show file tree

Hide file tree

Showing 5 changed files with 228 additions and 0 deletions.
diff --git a/docs/.vuepress/configuration/navbar/en.ts b/docs/.vuepress/configuration/navbar/en.ts
@@ -1,4 +1,5 @@
 export default {
+    ['navbar.migration'                                 ]: 'Migrate to v5.x',
     ['navbar.guide'                                     ]: 'Guide',
     ['navbar.developer'                                 ]: 'Plugin Development',
     ['navbar.architecture'                              ]: 'Architecture',

diff --git a/docs/.vuepress/configuration/navbar/index.ts b/docs/.vuepress/configuration/navbar/index.ts
@@ -12,6 +12,10 @@ const getNavbar = (lang: string): NavbarConfig => {
   const $ = (key: string) => strings[key] ?? key
 
   return [
+    {
+      text: $('navbar.migration'),
+      link: `/${lang}/migration/`,
+    },
     {
       text: $('navbar.guide'),
       link: `/${lang}/guide/`,

diff --git a/docs/.vuepress/configuration/navbar/zh.ts b/docs/.vuepress/configuration/navbar/zh.ts
@@ -1,4 +1,5 @@
 export default {
+    ['navbar.migration'                                 ]: '迁移到 v5.x',
     ['navbar.guide'                                     ]: '指南',
     ['navbar.developer'                                 ]: '插件开发',
     ['navbar.architecture'                              ]: '架构剖析',

diff --git a/docs/en/migration/README.md b/docs/en/migration/README.md
@@ -0,0 +1,111 @@
+# Migrate to v5.x
+
+## Transform API
+
+There are no changes to the Transform API and no migration is required.
+
+## Task API
+
+### VariantProcessor
+
+Replace `BaseVariant` with `Variant` in the `process` method:
+
+<Badge text="v4.x" />
+
+<CodeGroup>
+<CodeGroupItem title="Kotlin" active>
+
+```kotlin
+override fun process(variant: BaseVariant) {
+    // ...
+}
+```
+
+</CodeGroupItem>
+</CodeGroup>
+
+<Badge text="v5.x" />
+
+<CodeGroup>
+<CodeGroupItem title="Kotlin" active>
+
+```kotlin
+override fun process(variant: Variant) {
+    // ...
+}
+```
+
+</CodeGroupItem>
+</CodeGroup>
+
+## Gradle Compat
+
+### AGPInterface
+
+In Booster 5.0.0, all APIs with `BaseVariant` in `AGPInterface` have been replaced with `Variant`, and some `Task` related APIs have been deprecated. Although they have not been completely deleted, they are not recommended to be used and can basically be considered unusable -- the `Task` will be null at runtime.
+
+### Project Extension
+
+Similar to `AGPInterface`, the `Project` extension APIs in v4.x is retained as much as possible, the `BaseVariant` parameter in the method is replaced with `Variant`, and some methods are refactored.
+
+#### getAndroid / getAndroidOrNull
+
+Replace `Project.getAndroid(...)` with `Project.getAndroidComponents()`, and replace `Project.getAndroidOrNull(...)` with `Project.getAndroidComponentsOrNull()`:
+
+<Badge text="v4.x" />
+
+<CodeGroup>
+<CodeGroupItem title="Kotlin" active>
+
+```kotlin
+val android = getAndroidOrNull<BaseExtension>()
+```
+
+</CodeGroupItem>
+</CodeGroup>
+
+<Badge text="v5.x" />
+
+<CodeGroup>
+<CodeGroupItem title="Kotlin" active>
+
+```kotlin
+val androidComponents = getAndroidComponentsOrNull<AndroidComponentsExtension<*, *, *>>()
+```
+
+</CodeGroupItem>
+</CodeGroup>
+
+#### getResolvedArtifactResults
+
+Replace variant with filter in `Project.getResolvedArtifactResults(...)` method
+
+<Badge text="v4.x" />
+
+<CodeGroup>
+<CodeGroupItem title="Kotlin" active>
+
+```kotlin
+val result: Set<ResolvedArtifactResult> = project.getResolvedArtifactResults(
+    true,
+    variant
+)
+```
+
+</CodeGroupItem>
+</CodeGroup>
+
+<Badge text="v5.x" />
+
+<CodeGroup>
+<CodeGroupItem title="Kotlin" active>
+
+```kotlin
+val result: Set<ResolvedArtifactResult> = project.getResolvedArtifactResults(
+    true,
+    variant.filterByNameOrBuildType()
+)
+```
+
+</CodeGroupItem>
+</CodeGroup>
diff --git a/docs/zh/migration/README.md b/docs/zh/migration/README.md
@@ -0,0 +1,111 @@
+# 迁移到 v5.x
+
+## Transform API
+
+Transform API 没有任何变更，不需要做迁移。
+
+## Task API
+
+### VariantProcessor
+
+将 `process`  方法中的 `BaseVariant` 替换为 `Variant`：
+
+<Badge text="v4.x" />
+
+<CodeGroup>
+<CodeGroupItem title="Kotlin" active>
+
+```kotlin
+override fun process(variant: BaseVariant) {
+    // ...
+}
+```
+
+</CodeGroupItem>
+</CodeGroup>
+
+<Badge text="v5.x" />
+
+<CodeGroup>
+<CodeGroupItem title="Kotlin" active>
+
+```kotlin
+override fun process(variant: Variant) {
+    // ...
+}
+```
+
+</CodeGroupItem>
+</CodeGroup>
+
+## Gradle Compat
+
+### AGPInterface
+
+在 Booster 5.0.0 中，`AGPInterface` 中所有带 `BaseVariant` 的 API 已替换为 `Variant`，并废弃了一些 `Task` 相关的 API，虽然没有彻底删除，但不建议使用，基本上可以认为是不可用 -- 运行时无法获取到 AGP 的 `Task`
+
+### Project Extension
+
+和 `AGPInterface` 类似，尽可能保留了 v4.x 中存在的 API，将方法中的 `BaseVariant` 参数替换为了 `Variant`，个别方法做了重构。
+
+#### getAndroid / getAndroidOrNull
+
+将 `Project.getAndroid(...)` 替换为 `Project.getAndroidComponents()`；将 `Project.getAndroidOrNull(...)` 替换为 `Project.getAndroidComponentsOrNull()`：
+
+<Badge text="v4.x" />
+
+<CodeGroup>
+<CodeGroupItem title="Kotlin" active>
+
+```kotlin
+val android = getAndroidOrNull<BaseExtension>()
+```
+
+</CodeGroupItem>
+</CodeGroup>
+
+<Badge text="v5.x" />
+
+<CodeGroup>
+<CodeGroupItem title="Kotlin" active>
+
+```kotlin
+val androidComponents = getAndroidComponentsOrNull<AndroidComponentsExtension<*, *, *>>()
+```
+
+</CodeGroupItem>
+</CodeGroup>
+
+#### getResolvedArtifactResults
+
+将 `Project.getResolvedArtifactResults(...)` 方法中的 variant 替换为 filter：
+
+<Badge text="v4.x" />
+
+<CodeGroup>
+<CodeGroupItem title="Kotlin" active>
+
+```kotlin
+val result: Set<ResolvedArtifactResult> = project.getResolvedArtifactResults(
+    true,
+    variant
+)
+```
+
+</CodeGroupItem>
+</CodeGroup>
+
+<Badge text="v5.x" />
+
+<CodeGroup>
+<CodeGroupItem title="Kotlin" active>
+
+```kotlin
+val result: Set<ResolvedArtifactResult> = project.getResolvedArtifactResults(
+    true,
+    variant.filterByNameOrBuildType()
+)
+```
+
+</CodeGroupItem>
+</CodeGroup>