This is an automated email from the ASF dual-hosted git repository.
delei pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/fesod.git
The following commit(s) were added to refs/heads/main by this push:
new 5fb72f72 docs: add blog for migration with OpenRewrite (#910)
5fb72f72 is described below
commit 5fb72f72f3267286afe168ef33168115ae924dbb
Author: Bengbengbalabalabeng
<[email protected]>
AuthorDate: Tue Jun 23 21:52:11 2026 +0800
docs: add blog for migration with OpenRewrite (#910)
* docs(blog): add blog for migration with OpenRewrite
* fix: correct Apache Fesod to Apache Fesod (Incubating)
---------
Co-authored-by: DeleiGuo <[email protected]>
---
...07-migration-from-fastexcel-with-openrewrite.md | 214 +++++++++++++++++++++
...07-migration-from-fastexcel-with-openrewrite.md | 214 +++++++++++++++++++++
2 files changed, 428 insertions(+)
diff --git
a/website/blog/2026-05-07-migration-from-fastexcel-with-openrewrite.md
b/website/blog/2026-05-07-migration-from-fastexcel-with-openrewrite.md
new file mode 100644
index 00000000..a08ee707
--- /dev/null
+++ b/website/blog/2026-05-07-migration-from-fastexcel-with-openrewrite.md
@@ -0,0 +1,214 @@
+---
+title: "Automated Migration from FastExcel 1.3.0 to Apache Fesod (Incubating)
with OpenRewrite"
+description: Migrate FastExcel 1.3 to Apache Fesod (Incubating)
2.0.1-incubating
+authors: [bengbengbalabalabeng]
+tags: [migration, fastexcel, fesod]
+---
+
+> This article demonstrates how to write a declarative OpenRewrite recipe that
migrates your project from `cn.idev.excel:fastexcel:1.3.0` to
`org.apache.fesod:fesod-sheet:2.0.1-incubating`, covering both Maven and Gradle
builds.
+
+<!--truncate-->
+
+## Background
+
+FastExcel (`cn.idev.excel`) has been donated to the Apache Software Foundation
and is now incubating as **Apache Fesod (Incubating)**. The core change is a
**Java package path replacement** — the API, annotations, and processing logic
remain identical, making this a low-risk, mechanical refactoring.
+
+For the official migration strategy, see:
[https://fesod.apache.org/docs/migration/from-fastexcel/](https://fesod.apache.org/docs/migration/from-fastexcel/)
+
+Manually replacing imports file by file is tedious and error-prone.
OpenRewrite provides AST-level code transformation capabilities to perform this
kind of bulk migration precisely and safely.
+
+## Migration Scope
+
+1. Update Maven/Gradle dependencies
+2. Replace deprecated class names with `FesodSheet`
+3. Update package imports
+
+## Writing the OpenRewrite Recipe
+
+Create a `rewrite.yml` file in your project root:
+
+```yaml
+---
+type: specs.openrewrite.org/v1beta/recipe
+name: org.apache.fesod.MigrateFastExcelToFesod
+displayName: Migrate FastExcel 1.3 to Apache Fesod (Incubating)
2.0.1-incubating
+recipeList:
+
+ # Step 1: Update Dependencies (Maven & Gradle)
+ - org.openrewrite.maven.ChangeDependencyGroupIdAndArtifactId:
+ oldGroupId: cn.idev.excel
+ oldArtifactId: fastexcel
+ newGroupId: org.apache.fesod
+ newArtifactId: fesod-sheet
+ newVersion: 2.0.1-incubating
+ - org.openrewrite.gradle.ChangeDependency:
+ oldGroupId: cn.idev.excel
+ oldArtifactId: fastexcel
+ newGroupId: org.apache.fesod
+ newArtifactId: fesod-sheet
+ newVersion: 2.0.1-incubating
+
+ # Step 2: Package Import Updates
+ - org.openrewrite.java.ChangePackage:
+ oldPackageName: cn.idev.excel
+ newPackageName: org.apache.fesod.sheet
+ recursive: true
+ - org.openrewrite.java.ChangePackage:
+ oldPackageName: org.apache.fesod.excel
+ newPackageName: org.apache.fesod.sheet
+ recursive: true
+
+ # Step 3: Entry Class Rename
+ - org.openrewrite.java.ChangeType:
+ oldFullyQualifiedTypeName: org.apache.fesod.sheet.FastExcel
+ newFullyQualifiedTypeName: org.apache.fesod.sheet.FesodSheet
+ - org.openrewrite.java.ChangeType:
+ oldFullyQualifiedTypeName: org.apache.fesod.sheet.FastExcelFactory
+ newFullyQualifiedTypeName: org.apache.fesod.sheet.FesodSheet
+
+ - org.openrewrite.text.FindAndReplace:
+ find: ByFastExcelCGLIB
+ replace: ByFesodCGLIB
+ filePattern: "**/*.java"
+```
+
+### How It Works
+
+The recipe executes steps sequentially in declaration order:
+
+**Step 1 — Update Dependencies**: The first rule updates `pom.xml` for Maven
projects; the second rule updates `build.gradle` / `build.gradle.kts` for
Gradle projects. If your project uses only one build tool, the other rule is
silently skipped.
+
+**Step 2 — Package Import Updates**: `ChangePackage(recursive=true)` covers
all sub-packages under `cn.idev.excel` (annotation, read, write, converters,
enums, etc.) in a single rule — no need to enumerate each one individually. The
second rule handles legacy code that was already partially migrated to
`org.apache.fesod.excel`. After this step, imports like
`cn.idev.excel.FastExcel` become `org.apache.fesod.sheet.FastExcel` (the
`@Deprecated` bridge class in Fesod).
+
+**Step 3 — Entry Class Rename**: Once Step 2 completes, all `FastExcel` and
`FastExcelFactory` imports are unified under `org.apache.fesod.sheet`. Only two
`ChangeType` rules are needed to rename them to the canonical `FesodSheet`
class, automatically updating all call sites (`FastExcel.read()`,
`FastExcel.write()`, etc.) and type references (variable declarations, class
literals).
+
+**Step 4 — CGLIB String Replacement**: Only affects code that references
CGLIB-generated class names at runtime. Most projects don't need this step —
the rule is silently skipped if there's no match.
+
+## Adding OpenRewrite to Your Project
+
+### Maven
+
+Add the plugin to `pom.xml`:
+
+```xml
+<plugin>
+ <groupId>org.openrewrite.maven</groupId>
+ <artifactId>rewrite-maven-plugin</artifactId>
+ <version>6.38.0</version>
+ <configuration>
+ <activeRecipes>
+ <recipe>org.apache.fesod.MigrateFastExcelToFesod</recipe>
+ </activeRecipes>
+ </configuration>
+</plugin>
+```
+
+### Gradle (Groovy)
+
+Add to `build.gradle`:
+
+```groovy
+plugins {
+ id 'java'
+ id 'maven-publish'
+ id 'org.openrewrite.rewrite' version '7.32.2'
+}
+
+rewrite {
+ activeRecipe(
+ 'org.apache.fesod.MigrateFastExcelToFesod',
+ )
+}
+```
+
+### Gradle (Kotlin)
+
+Add to `build.gradle.kts`:
+
+```kotlin
+plugins {
+ `java-library`
+ `maven-publish`
+ id("org.openrewrite.rewrite") version "7.32.2"
+}
+
+rewrite {
+ activeRecipe(
+ "org.apache.fesod.MigrateFastExcelToFesod",
+ )
+}
+```
+
+## Running the Migration
+
+### Preview Changes
+
+View what the recipe would change without modifying files:
+
+```bash
+# Maven
+# Output: target/site/rewrite/rewrite.patch
+mvn rewrite:dryRun
+
+# Gradle
+# Output: build/reports/rewrite/rewrite.patch
+gradle rewriteDryRun
+```
+
+### Apply Changes
+
+Once satisfied with the preview, apply the changes:
+
+```bash
+# Maven
+mvn rewrite:run
+
+# Gradle
+gradle rewriteRun
+```
+
+### Verify
+
+```bash
+# Compile check
+mvn compile
+# or
+gradle compileJava
+
+# Run tests
+mvn test
+# or
+gradle test
+```
+
+## Before and After
+
+Before migration:
+
+```java
+import cn.idev.excel.FastExcel;
+import cn.idev.excel.annotation.ExcelProperty;
+import cn.idev.excel.read.listener.ReadListener;
+
+FastExcel.write(outputStream, BookData.class)
+ .sheet("Sheet1")
+ .doWrite(data());
+```
+
+After migration:
+
+```java
+import org.apache.fesod.sheet.FesodSheet;
+import org.apache.fesod.sheet.annotation.ExcelProperty;
+import org.apache.fesod.sheet.read.listener.ReadListener;
+
+FesodSheet.write(outputStream, BookData.class)
+ .sheet("Sheet1")
+ .doWrite(data());
+```
+
+## References
+
+- Apache Fesod (Incubating) Official Migration Guide:
[https://fesod.apache.org/docs/migration/from-fastexcel/](https://fesod.apache.org/docs/migration/from-fastexcel/)
+- OpenRewrite Documentation:
[https://docs.openrewrite.org/](https://docs.openrewrite.org/)
+- OpenRewrite Recipe Reference:
[https://docs.openrewrite.org/recipes](https://docs.openrewrite.org/recipes)
diff --git
a/website/i18n/zh-cn/docusaurus-plugin-content-blog/2026-05-07-migration-from-fastexcel-with-openrewrite.md
b/website/i18n/zh-cn/docusaurus-plugin-content-blog/2026-05-07-migration-from-fastexcel-with-openrewrite.md
new file mode 100644
index 00000000..9c155f99
--- /dev/null
+++
b/website/i18n/zh-cn/docusaurus-plugin-content-blog/2026-05-07-migration-from-fastexcel-with-openrewrite.md
@@ -0,0 +1,214 @@
+---
+title: "使用 OpenRewrite 从 FastExcel 1.3.0 自动迁移到 Apache Fesod (Incubating)"
+description: 将 FastExcel 1.3 迁移至 Apache Fesod (Incubating) 2.0.1-incubating
+authors: [bengbengbalabalabeng]
+tags: [migration, fastexcel, fesod]
+---
+
+> 本文介绍如何利用 OpenRewrite 编写声明式迁移配置，将项目从 `cn.idev.excel:fastexcel:1.3.0` 迁移至
`org.apache.fesod:fesod-sheet:2.0.1-incubating`，适用于 Maven 与 Gradle 项目。
+
+<!--truncate-->
+
+## 背景
+
+FastExcel（`cn.idev.excel`）已捐赠给 Apache 软件基金会，孵化为 **Apache Fesod
(Incubating)**。迁移的核心变化是 **Java 包路径替换**——API、注解和处理逻辑完全一致，属于低风险的机械重构。
+
+官方迁移策略参考：[https://fesod.apache.org/docs/migration/from-fastexcel/](https://fesod.apache.org/docs/migration/from-fastexcel/)
+
+手动逐文件替换 import 既耗时又容易遗漏。OpenRewrite 提供了 AST 级别的代码变换能力，能精确、安全地完成这类批量迁移。
+
+## 迁移范围
+
+1. 更新 Maven/Gradle 依赖
+2. 将已废弃的类名替换为 `FesodSheet`
+3. 更新包导入
+
+## 编写 OpenRewrite Recipe
+
+在项目根目录创建文件 `rewrite.yml`：
+
+```yaml
+---
+type: specs.openrewrite.org/v1beta/recipe
+name: org.apache.fesod.MigrateFastExcelToFesod
+displayName: Migrate FastExcel 1.3 to Apache Fesod (Incubating)
2.0.1-incubating
+recipeList:
+
+ # 步骤 1：更新依赖 (Maven & Gradle)
+ - org.openrewrite.maven.ChangeDependencyGroupIdAndArtifactId:
+ oldGroupId: cn.idev.excel
+ oldArtifactId: fastexcel
+ newGroupId: org.apache.fesod
+ newArtifactId: fesod-sheet
+ newVersion: 2.0.1-incubating
+ - org.openrewrite.gradle.ChangeDependency:
+ oldGroupId: cn.idev.excel
+ oldArtifactId: fastexcel
+ newGroupId: org.apache.fesod
+ newArtifactId: fesod-sheet
+ newVersion: 2.0.1-incubating
+
+ # 步骤 2：更新包导入
+ - org.openrewrite.java.ChangePackage:
+ oldPackageName: cn.idev.excel
+ newPackageName: org.apache.fesod.sheet
+ recursive: true
+ - org.openrewrite.java.ChangePackage:
+ oldPackageName: org.apache.fesod.excel
+ newPackageName: org.apache.fesod.sheet
+ recursive: true
+
+ # 步骤 3：重命名入口类
+ - org.openrewrite.java.ChangeType:
+ oldFullyQualifiedTypeName: org.apache.fesod.sheet.FastExcel
+ newFullyQualifiedTypeName: org.apache.fesod.sheet.FesodSheet
+ - org.openrewrite.java.ChangeType:
+ oldFullyQualifiedTypeName: org.apache.fesod.sheet.FastExcelFactory
+ newFullyQualifiedTypeName: org.apache.fesod.sheet.FesodSheet
+
+ - org.openrewrite.text.FindAndReplace:
+ find: ByFastExcelCGLIB
+ replace: ByFesodCGLIB
+ filePattern: "**/*.java"
+```
+
+### 执行逻辑解析
+
+Recipe 按声明顺序依次执行，分为四个步骤：
+
+**Step 1 — 更新依赖**：Maven 项目触发第一条规则修改 `pom.xml`；Gradle 项目触发第二条规则修改
`build.gradle` / `build.gradle.kts`。如果项目只使用其中一种构建工具，另一条规则自动跳过，不会报错。
+
+**Step 2 — 更新包导入**：`ChangePackage(recursive=true)` 一条规则覆盖 `cn.idev.excel`
下所有子包（annotation、read、write、converters、enums 等），无需逐个枚举。第二条规则处理已部分迁移到
`org.apache.fesod.excel` 的遗留代码。这一步会将 `cn.idev.excel.FastExcel` 的 import 改为
`org.apache.fesod.sheet.FastExcel`（Fesod 中的 `@Deprecated` 桥接类）。
+
+**Step 3 — 重命名入口类**：Step 2 完成后，所有 `FastExcel` 和 `FastExcelFactory` 的 import
已统一指向 `org.apache.fesod.sheet` 包。此时只需两条 `ChangeType` 规则，将它们改为正式的 `FesodSheet`
类，同时自动处理所有调用点（`FastExcel.read()`、`FastExcel.write()` 等）和类型引用（变量声明、类字面量）。
+
+**Step 4 — CGLIB 字符串替换**：仅对引用了 CGLIB 生成类名的代码生效，多数项目不需要此步骤，不匹配则自动跳过。
+
+## 在项目中引入 OpenRewrite
+
+### Maven 项目
+
+在 `pom.xml` 中添加插件：
+
+```xml
+<plugin>
+ <groupId>org.openrewrite.maven</groupId>
+ <artifactId>rewrite-maven-plugin</artifactId>
+ <version>6.38.0</version>
+ <configuration>
+ <activeRecipes>
+ <recipe>org.apache.fesod.MigrateFastExcelToFesod</recipe>
+ </activeRecipes>
+ </configuration>
+</plugin>
+```
+
+### Gradle (Groovy)
+
+在 `build.gradle` 中引入：
+
+```groovy
+plugins {
+ id 'java'
+ id 'maven-publish'
+ id 'org.openrewrite.rewrite' version '7.32.2'
+}
+
+rewrite {
+ activeRecipe(
+ 'org.apache.fesod.MigrateFastExcelToFesod',
+ )
+}
+```
+
+### Gradle (Kotlin)
+
+```kotlin
+plugins {
+ `java-library`
+ `maven-publish`
+ id("org.openrewrite.rewrite") version "7.32.2"
+}
+
+rewrite {
+ activeRecipe(
+ "org.apache.fesod.MigrateFastExcelToFesod",
+ )
+}
+```
+
+## 执行迁移
+
+### 预览变更
+
+先查看 Recipe 会产生哪些修改，不实际改动文件：
+
+```bash
+# Maven
+# 默认输出路径：target/site/rewrite/rewrite.patch
+mvn rewrite:dryRun
+
+# Gradle
+# 默认输出路径：build/reports/rewrite/rewrite.patch
+gradle rewriteDryRun
+```
+
+输出会列出所有即将修改的文件和具体变更内容。
+
+### 执行迁移
+
+确认无误后，执行实际修改：
+
+```bash
+# Maven
+mvn rewrite:run
+
+# Gradle
+gradle rewriteRun
+```
+
+### 验证
+
+```bash
+# 编译检查
+mvn compile
+# 或
+gradle compileJava
+
+# 运行测试
+mvn test
+# 或
+gradle test
+```
+
+## 迁移效果示例
+
+迁移前：
+
+```java
+import cn.idev.excel.FastExcel;
+import cn.idev.excel.annotation.ExcelProperty;
+import cn.idev.excel.read.listener.ReadListener;
+
+FastExcel.write(outputStream, BookData.class)
+ .sheet("Sheet1")
+ .doWrite(data());
+```
+
+迁移后：
+
+```java
+import org.apache.fesod.sheet.FesodSheet;
+import org.apache.fesod.sheet.annotation.ExcelProperty;
+import org.apache.fesod.sheet.read.listener.ReadListener;
+
+FesodSheet.write(outputStream, BookData.class)
+ .sheet("Sheet1")
+ .doWrite(data());
+```
+
+## 参考
+
+- Apache Fesod (Incubating)
官方迁移指南：[https://fesod.apache.org/docs/migration/from-fastexcel/](https://fesod.apache.org/docs/migration/from-fastexcel/)
+- OpenRewrite
官方文档：[https://docs.openrewrite.org/](https://docs.openrewrite.org/)
+- OpenRewrite Recipe
参考：[https://docs.openrewrite.org/recipes](https://docs.openrewrite.org/recipes)
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
