This is an automated email from the ASF dual-hosted git repository. sxnan pushed a commit to branch release-0.2 in repository https://gitbox.apache.org/repos/asf/flink-agents.git
commit 4e7d32cef0b07da1760b796915c779460f09ea28 Author: xuannan.sxn <[email protected]> AuthorDate: Thu Mar 19 11:37:32 2026 +0800 [AONE-80306915] Add internal fork workflow docs Document internal fork branching, versioning, and release workflow. Upstream-candidate: no --- INTERNAL_DEVELOPMENT.md | 364 ++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 6 +- 2 files changed, 369 insertions(+), 1 deletion(-) diff --git a/INTERNAL_DEVELOPMENT.md b/INTERNAL_DEVELOPMENT.md new file mode 100644 index 00000000..202c6f80 --- /dev/null +++ b/INTERNAL_DEVELOPMENT.md @@ -0,0 +1,364 @@ +# Flink Agents 内部仓库维护 + +## 1. 概述 + +本文档描述基于 [apache/flink-agents](https://github.com/apache/flink-agents) 维护内部 Fork 的完整工作流。 + +### 1.1 目标 + +- 内部 patch 可追踪、可回馈社区，新开发 patch 保持独立便于 cherry-pick。 +- 切 release 分支前通过 merge 固化内部 patch，避免 rebase 负担累积。 +- 定期与上游 `main` 和 `release-*` 分支同步。 +- 内部修改可识别、可追踪、可回馈社区。 + +### 1.2 Git Remote 约定 + +| Remote | 指向 | 用途 | +|------------|-----------------------------------|-----------------------| +| `upstream` | `github.com:apache/flink-agents` | 社区仓库（只读） | +| `origin` | 内部 GitLab 仓库 | 内部 Fork（推送目标） | + +--- + +## 2. 分支管理 + +### 2.1 分支模型 + +内部仓库的分支命名与社区保持一致，不加额外前缀。内部 patch 通过 commit message 中的 `[AONE-XXXX]` 前缀来识别。 + +#### 2.1.1 Main 分支：日常 Rebase，切 Release 前 Merge + +日常开发时内部 patch 通过 rebase 叠加，保持独立便于推社区。**在切 release 分支之前**，固定执行 merge `upstream/main` 固化所有内部 patch。 + +``` +upstream/main ───A───B───C───D───E───F───G───H───I─── + │ │ + │ 日常开发 │ 切 release 前 merge 固化 + ▼ ▼ +origin/main ───────[AONE-1]───[AONE-2]───[AONE-3]───merge─── + │ + └── 固化所有内部 patch +``` + +**说明**： +- 在社区一个版本的开发周期中，尽量把可以推社区的 patch 都推到社区 +- 切 release 分支前，rebase upstream/main 去除已合入的 patch，然后 merge 固化剩余内部 patch +- merge 固化的目的是减少后续 rebase 负担，固化后的 patch 仍可从历史中 cherry-pick 推社区 + +#### 2.1.2 Release 维护分支：Merge Main，保持 SNAPSHOT + +创建 `release-x.y` 维护分支时，将 `main` 分支 merge 进来，并将版本设置为 `x.y-vvr-SNAPSHOT`。正式发版时，再从 `release-x.y` 切出 `release/x.y-vvr-a.b.c` 发布分支并设置正式版本。 + +``` +upstream/release-0.3 ───X───Y───Z─── + │ + │ merge origin/main + ▼ +origin/release-0.3 ───────────merge───[set 0.3-vvr-SNAPSHOT]─── + │ + └── cut release/0.3-vvr-11.6.0 +``` + +**说明**： +- 由于 main 分支已在切分支前做过 merge 固化，`release-x.y` 的 merge 通常无冲突 +- `release-x.y` 是长期维护分支，会继续通过 merge 同步上游 bugfix +- `release/x.y-vvr-a.b.c` 是一次性正式发布分支，不再定期同步上游 + +### 2.2 Patch 管理策略 + +| 阶段 | 操作 | 目的 | +|------|------|------| +| 日常开发 | rebase upstream/main | patch 保持独立，便于推社区 | +| 切 release 前 | merge upstream/main | 固化内部 patch，减少后续 rebase 负担 | +| 创建 release 维护分支 | merge origin/main + 设置 `x.y-vvr-SNAPSHOT` | 内部 patch 进入 `release-x.y` | +| 正式发版 | 从 `release-x.y` 切 `release/x.y-vvr-a.b.c` + 设置正式版本 | 产出可发布代码快照 | + +### 2.3 分支职责 + +| 分支 | 基于 | 策略 | 用途 | 生命周期 | +|------|------|------|------|----------| +| `main` | `upstream/main` | 日常 rebase，切 release 前 merge 固化 | 主开发分支 | 长期存在 | +| `release-x.y` | `upstream/release-x.y` | Merge | 内部 release 维护分支（`SNAPSHOT`） | 跟随上游 release 分支生命周期 | +| `release/x.y-vvr-a.b.c` | `release-x.y` | 不同步上游，只封版版本号 | 内部正式发布分支 | 发布后冻结 | + +除 `main`、`release-*` 和 `release/*` 外的所有分支均视为功能开发分支，通过 PR 合入 `main`，合入后删除。 + +### 2.4 Release 维护分支与正式发布分支 + +- 等上游 `release-x.y` 分支创建后，基于其创建内部维护分支 `release-x.y`。 +- 将 `main` 分支 merge 到 `release-x.y`（内部 patch 已在 main 上处理过），并保持版本为 `x.y-vvr-SNAPSHOT`。 +- `release-x.y` 通过 `tools/internal/sync_upstream.sh release-x.y` 定期同步上游 release 分支的 bugfix。 +- 每次正式发版时，从 `release-x.y` 切出 `release/x.y-vvr-a.b.c`，将版本设置为正式版本后构建发布。 +- 发布后如需 hotfix，应先修复 `release-x.y`，再切出新的正式发布分支；不要继续修改已发布分支。 + +### 2.5 多 Release 分支并存 + +当同时维护多个 release 线时，维护分支与正式发布分支并存： + +``` +origin/release-0.2 → 0.2-vvr-SNAPSHOT +origin/release/0.2-vvr-11.5.0 → 0.2-vvr-11.5.0 +origin/release/0.2-vvr-11.5.1 → 0.2-vvr-11.5.1 + +origin/release-0.3 → 0.3-vvr-SNAPSHOT +origin/release/0.3-vvr-11.6.0 → 0.3-vvr-11.6.0 +``` + +**说明**： +- 每个 `release-x.y` 维护分支独立维护，可切出多个正式发布分支 +- `main` 和 `release-x.y` 都使用 `SNAPSHOT` 版本；`release/x.y-vvr-a.b.c` 才使用精确 VVR 版本 +- Hotfix 需要根据影响范围决定合入哪些维护分支；已发布分支只保留对应版本的封版状态 + +### 2.6 Hotfix 流程 + +当需要对已发布版本做紧急修复时： + +```bash +# 1. 基于 release 维护分支创建 hotfix 分支 +git checkout -b hotfix/AONE-XXXX release-0.3 + +# 2. 开发并测试 hotfix +# ... + +# 3. 合入 release 维护分支 +git checkout release-0.3 +git merge hotfix/AONE-XXXX --no-ff + +# 4. 如果问题也影响 main，cherry-pick 到 main +git checkout main +git cherry-pick <hotfix-commit> + +# 5. 如果需要重新发布，从 release-0.3 切新的正式发布分支 +./tools/internal/create_release_publish_branch.sh 0.3 11.6.1 + +# 6. 清理 hotfix 分支 +git branch -d hotfix/AONE-XXXX +``` + +**说明**： +- 不要直接在 `release/0.3-vvr-11.6.0` 上继续提交 hotfix +- 已发布版本需要修复时，应在 `release-0.3` 修复后重新切 `release/0.3-vvr-11.6.1` + +### 2.7 禁止事项 + +- **不要直接修改 `upstream/*` 跟踪分支。** 它们应始终是社区的干净镜像。 +- **不要在非切 release 的时机做 merge 固化。** merge 固化固定在切 release 分支之前进行。 +- **不要在已发布分支 `release/x.y-vvr-a.b.c` 上继续接 hotfix。** 修复应进入 `release-x.y`，然后重新切新发布分支。 + +--- + +## 3. Commit 规范 + +### 3.1 前缀约定 + +所有内部 commit **必须**使用 `[AONE-XXXX]` 前缀（XXXX 为 AONE 任务号）： + +``` +[AONE-1234] Add VVP deployment support for workflow jobs +[AONE-5678] Customize token metrics collection +``` + +### 3.2 Commit 粒度 + +- **原子化**：一个 commit 只做一件事。 +- **自包含**：每个 commit 上代码都能编译通过。 +- **不混杂**：不要在同一个 commit 中混合无关改动。 + +### 3.3 Commit Body + +在 body 中可直接补充必要的背景说明，并标注是否适合推社区： + +``` +[AONE-1234] Add custom model provider for Tongyi + +Internal deployment requires Tongyi model provider. +Upstream-candidate: yes +``` + +`Upstream-candidate: yes` 用于标记适合贡献回社区的 patch，便于后续通过 `git log --grep` 批量筛选出候选 commit，统一整理后向社区提交。 + +--- + +## 4. 版本管理 + +### 4.1 版本号格式 + +内部版本基于社区的 **SNAPSHOT 开发版本**（如 `0.3-SNAPSHOT`），不依赖社区的具体正式发布版本（如 `0.3.0`、`0.3.1`）。内部版本号格式为 `x.y-vvr-a.b.c`，其中： +- `x.y`：对应开源 flink-agents 版本号 +- `a.b.c`：对应 VVR 版本号 + +| 类型 | Java (Maven) | Python (PEP 440) | 分支 | 说明 | +|------|-------------|------------------|------|------| +| 主开发中 | `0.4-vvr-SNAPSHOT` | `0.4+vvr.dev0` | `main` | 主开发分支，不对应具体 VVR 版本 | +| Release 维护中 | `0.3-vvr-SNAPSHOT` | `0.3+vvr.dev0` | `release-0.3` | release 维护分支，持续同步上游 bugfix | +| 正式发布 | `0.3-vvr-11.6.0` | `0.3+vvr.11.6.0` | `release/0.3-vvr-11.6.0` | 对应 VVR 11.6.0 的封版分支 | + +> **开发版本号说明**：`main` 和 `release-x.y` 都属于开发中的分支，因此都使用 `-vvr-SNAPSHOT` / `+vvr.dev0` 格式。区别仅在于它们所对应的开源版本线不同。 + +> **Python 版本说明**：使用 PEP 440 的 [local version label](https://peps.python.org/pep-0440/#local-version-identifiers)（`+vvr.a.b.c` 后缀）。排序正确。带 `+` 的 local version 不能上传到公共 PyPI，仅适用于内部 PyPI。 + +### 4.2 版本号修改位置 + +修改内部版本号时，需同时更新以下位置： + +| 文件 | 说明 | +|------|------| +| `pom.xml`（根 + 所有子模块） | Java 版本，通过 `mvn versions:set` 批量修改 | +| `python/pyproject.toml` | Python 版本 | +| `docs/config.toml` | 文档版本（如需要） | + +建议创建 `tools/internal/update_version.sh` 脚本，基于社区的 `tools/releasing/update_branch_version.sh` 扩展，一次性更新所有版本号位置。脚本需要分别处理 Java 和 Python 的版本号格式差异： + +```bash +# Java 版本号格式 +JAVA_VERSION="0.3-vvr-11.6.0" + +# Python 版本号格式（将 -vvr- 替换为 +vvr.） +PYTHON_VERSION="0.3+vvr.11.6.0" +``` + +### 4.3 发版版本号 + +- **main 分支**始终使用开发版本号（`-vvr-SNAPSHOT` / `+vvr.dev0`），不发版。 +- **release-x.y 维护分支**始终使用开发版本号（`-vvr-SNAPSHOT` / `+vvr.dev0`），用于同步上游和承接 hotfix。 +- **正式发布分支 `release/x.y-vvr-a.b.c`** 使用正式版本号（`-vvr-a.b.c` / `+vvr.a.b.c`）。 +- 内部发版时，从 `release-x.y` 切 `release/x.y-vvr-a.b.c`，通过 `tools/internal/update_version.sh` 设置正式版本号，提交后构建发布产物。 +- 已发布分支不再定期同步上游，也不继续积累开发提交。 + +--- + +## 5. 上游同步与 Patch 管理 + +### 5.1 同步频率 + +- **常规频率：每周一次**（建议每周一）。 +- **强制同步：每次内部发版前。** +- 上游有大版本发布或 breaking change 时，尽快同步。 + +### 5.2 切 Release 分支前的处理流程 + +在切 release 分支之前，固定执行以下流程： + +```bash +# 1. 审视 main 上的所有 patch +git log upstream/main..HEAD --oneline + +# 2. 筛选可推社区的 patch，提交 PR 到上游 +# 等待合入或明确拒绝 + +# 3. 同步上游（已合入的 patch 会自动去除） +git fetch upstream +git rebase upstream/main + +# 4. 再次确认剩余的 patch +git log upstream/main..HEAD --oneline + +# 5. merge 固化剩余内部 patch（为切 release 做准备） +git merge upstream/main -m "[internal] Merge upstream before release" +``` + +固化后历史变为： +``` +upstream/main ───G───H───I─── + │ │ + │ │ merge 固化 + │ ▼ +origin/main ───[AONE-1]───[AONE-2]───merge─── +``` + +**说明**：merge 后内部 patch 不再参与后续 rebase，减少冲突负担。 + +### 5.3 创建 Release 维护分支流程 + +在 main 分支完成 merge 固化后（参考 5.2），创建 `release-x.y` 维护分支： + +```bash +# 1. 基于 upstream release 分支创建 +git checkout -b release-0.3 upstream/release-0.3 + +# 2. Merge main 到 release 维护分支 +git merge origin/main --no-ff -m "[internal] Merge internal patches into release-0.3" + +# 3. 保持 release 维护分支为 SNAPSHOT 版本 +./tools/internal/update_version.sh 0.3-vvr-SNAPSHOT +``` + +也可以直接使用脚本： + +```bash +./tools/internal/create_release_branch.sh 0.3 +``` + +### 5.4 创建正式发布分支流程 + +当需要发布 VVR 11.6.0 时，从 `release-0.3` 切正式发布分支： + +```bash +# 1. 切到 release 维护分支 +git checkout release-0.3 + +# 2. 基于 release 维护分支创建正式发布分支 +git checkout -b release/0.3-vvr-11.6.0 + +# 3. 设置正式版本号 +./tools/internal/update_version.sh 0.3-vvr-11.6.0 +``` + +也可以直接使用脚本： + +```bash +./tools/internal/create_release_publish_branch.sh 0.3 11.6.0 +``` + +### 5.5 Release 维护分支后续同步 + +```bash +# 同步上游 bugfix 到 release 维护分支 +git fetch upstream +git merge upstream/release-0.3 + +# 正式发布分支 release/0.3-vvr-11.6.0 不再同步上游 +``` + +### 5.6 同步脚本 + +提供自动化脚本 `tools/internal/sync_upstream.sh`，统一处理 `main` 和 `release-*` 维护分支的同步。脚本核心流程： + +1. `git fetch upstream` 拉取上游最新代码 +2. 检查 `upstream/<branch>` 是否有新 commit，无则退出 +3. 创建备份分支 `<branch>-backup-<timestamp>` +4. 对于 main 分支：执行 `git rebase upstream/main` +5. 对于 `release-*` 维护分支：执行 `git merge upstream/release-x.y` +6. 运行 `./tools/build.sh` 验证构建 +7. 输出同步摘要，等待人工确认后 push + +异常处理： + +- **Rebase 冲突**：自动 `git rebase --abort` 回退，打印冲突文件列表，提示人工处理。 +- **构建失败**：自动回退到备份分支，打印构建日志位置。 +- **误传正式发布分支**：脚本直接拒绝处理 `release/x.y-vvr-a.b.c`，避免把封版分支与上游继续同步。 + +### 5.7 Force-push 后的团队协作 + +上游同步可能导致 `origin/main` 被 force-push。完成同步后应通知团队，团队成员需执行以下操作来更新本地分支： + +```bash +git fetch origin +git reset --hard origin/main +``` + +如果本地有未推送的功能分支基于旧的 `main`，需要 rebase 到新的 `origin/main` 上。 + +### 5.8 冲突处理原则 + +1. **先理解上游改动**：解决冲突前，先读上游 commit 的 message 和 diff，理解其意图。 +2. **优先保留上游意图**：有疑问时，以上游改动为准，调整内部 patch 去适配。 +3. **确保内部 patch 目标不丢失**：解决后内部 patch 仍应实现其原始目的。 +4. **上游已实现相同功能时**：使用 `git rebase --skip` 丢弃内部 patch。 +5. **过于复杂时先回退**：用 `git rebase --abort` 回退，寻求团队帮助。 + +--- + +## 附录 A: 备选方案——以依赖方式扩展 + +曾考虑不 fork 仓库，而是将 `flink-agents` 作为 Maven / PyPI 依赖，通过类覆盖（Java classpath 优先级）或 monkey patching（Python）来修改已有行为。该方案对"添加新 integration"可行，但对"修改已有行为"无法提供可靠的覆盖机制——尤其是 Python 侧缺乏等价的 classpath 优先级机制。考虑到本项目 Java 和 Python 代码通过 PemJa JNI 桥接紧密耦合，且内部开发不可避免地需要修改 runtime 逻辑等已有行为，Fork + Rebase/Merge 混合方案在可维护性和可靠性上显著优于依赖扩展方案，因此否决了该备选方案。 diff --git a/README.md b/README.md index e3c98c3d..e73dda5d 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,10 @@ Apache Flink Agents is an Agentic AI framework based on Apache Flink. [User Documentation](https://nightlies.apache.org/flink/flink-agents-docs-main/) +> Internal fork note: +> This repository extends the open source [apache/flink-agents](https://github.com/apache/flink-agents) project for internal use. +> For internal branch, version, and release workflow, see [INTERNAL_DEVELOPMENT.md](INTERNAL_DEVELOPMENT.md). + ## Building Prerequisites for building Flink Agents: @@ -41,4 +45,4 @@ See the [Apache Flink website](https://flink.apache.org/what-is-flink/community/ ### Community Sync -There is a weekly online sync. Everyone is welcome to join. Please find the schedule, agenda for the next sync, and records of previous syncs in this [github discussion page](https://github.com/apache/flink-agents/discussions/66). \ No newline at end of file +There is a weekly online sync. Everyone is welcome to join. Please find the schedule, agenda for the next sync, and records of previous syncs in this [github discussion page](https://github.com/apache/flink-agents/discussions/66).
