This is an automated email from the ASF dual-hosted git repository. github-merge-queue[bot] pushed a commit to branch gh-readonly-queue/dev/pr-11970-e6caf5a4b337803d866e877dab86541e6d15a364 in repository https://gitbox.apache.org/repos/asf/seatunnel.git
commit a38f63109caf84ef3188003142b3ff98e83e3062 Author: zhiwei.niu <[email protected]> AuthorDate: Fri Aug 28 02:43:14 2026 +0000 [Improve][CI] Refine Merge Queue fallback and documentation (#11970) --- .asf.yaml | 11 ++++--- .github/workflows/merge_queue.yml | 26 +++++---------- docs/en/developer/merge-queue.md | 66 +++++++++++++++++++++++++++++++++++++++ docs/sidebars.js | 1 + docs/zh/developer/merge-queue.md | 66 +++++++++++++++++++++++++++++++++++++++ 5 files changed, 147 insertions(+), 23 deletions(-) diff --git a/.asf.yaml b/.asf.yaml index 6986e38ef6..d146f3b201 100644 --- a/.asf.yaml +++ b/.asf.yaml @@ -13,7 +13,6 @@ # See the License for the specific language governing permissions and # limitations under the License. # - github: description: SeaTunnel is a multimodal, high-performance, distributed, massive data integration tool. homepage: https://seatunnel.apache.org/ @@ -54,7 +53,11 @@ github: - name: Merge Queue target: branch enforcement: active - bypass_actors: [] + bypass_actors: + # apache/root — ASF Infra team. + - actor_id: 118420 + actor_type: Team + bypass_mode: always conditions: ref_name: include: @@ -63,8 +66,8 @@ github: rules: - type: merge_queue parameters: - # Leave time for runner scheduling and status reporting around the 30-minute job. - check_response_timeout_minutes: 45 + # Allow enough time for runner scheduling before the 30-minute job starts. + check_response_timeout_minutes: 120 grouping_strategy: ALLGREEN max_entries_to_build: 5 # Phase one merges each PR immediately instead of waiting to form a batch. diff --git a/.github/workflows/merge_queue.yml b/.github/workflows/merge_queue.yml index 17505af636..35b67320bb 100644 --- a/.github/workflows/merge_queue.yml +++ b/.github/workflows/merge_queue.yml @@ -44,24 +44,12 @@ jobs: cache: maven # Compile the standard modules with the CI profile. - name: Compile main and test sources - uses: nick-fields/retry@v3 - with: - timeout_minutes: 28 - max_attempts: 3 - retry_wait_seconds: 10 - retry_on: error - command: | - ./mvnw -B -T 1C -Pci clean install -DskipTests \ - -D"license.skipAddThirdParty"=true -D"skip.ui"=true \ - --no-snapshot-updates + run: | + ./mvnw -B -T 1C -Pci clean install -DskipTests \ + -D"license.skipAddThirdParty"=true -D"skip.ui"=true \ + --no-snapshot-updates # Build the opt-in seatunnel-benchmarks module with its dedicated profile. - name: Compile benchmark main and test sources - uses: nick-fields/retry@v3 - with: - timeout_minutes: 8 - max_attempts: 3 - retry_wait_seconds: 10 - retry_on: error - command: | - ./mvnw -B -Pbenchmark -pl seatunnel-benchmarks clean install -DskipTests \ - -D"license.skipAddThirdParty"=true --no-snapshot-updates + run: | + ./mvnw -B -Pbenchmark -pl seatunnel-benchmarks clean install -DskipTests \ + -D"license.skipAddThirdParty"=true --no-snapshot-updates diff --git a/docs/en/developer/merge-queue.md b/docs/en/developer/merge-queue.md new file mode 100644 index 0000000000..4bb729ad4e --- /dev/null +++ b/docs/en/developer/merge-queue.md @@ -0,0 +1,66 @@ +# Merge Pull Requests with Merge Queue + +SeaTunnel uses [GitHub Merge Queue](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request-with-a-merge-queue) for pull requests targeting `dev`. The queue validates a pull request against the latest `dev` commit immediately before merge. + +## Add a Pull Request to the Queue + +1. Confirm that the pull request has the required approval and a successful pull-request `Build`. +2. Select **Merge when ready**. +3. GitHub creates a temporary branch named like `gh-readonly-queue/dev/pr-<number>-<sha>`. +4. The `Merge Queue` workflow runs the required `Build` against that temporary commit. +5. If the build succeeds, GitHub squash-merges the pull request into `dev`. + +The queue build compiles the standard Maven reactor with the `ci` profile and then compiles `seatunnel-benchmarks` with the `benchmark` profile. Both commands use `-DskipTests`: tests are not executed, but main and test sources are compiled. + +## Find Why a Pull Request Left the Queue + +When a required check fails, times out, or the temporary commit conflicts with `dev`, GitHub removes the pull request from the queue and records the reason in the pull request timeline. + +1. Open the pull request and find the merge-queue removal event in the timeline. +2. Follow the failed `Build` or **Details** link to the workflow run. +3. If the timeline does not provide a run link, open **Actions** in `apache/seatunnel`, select **Merge Queue**, and find the run whose branch contains `pr-<pull-request-number>-`. +4. Open the `Build` job and expand the failed step: + - `Compile main and test sources` + - `Compile benchmark main and test sources` +5. Search the log for the first Maven `[ERROR]` or `BUILD FAILURE`. The final `Process completed with exit code 1` line only reports the result; the useful cause normally appears earlier. + +If the browser view is truncated or difficult to search, use **Download log archive** from the run page. With GitHub CLI, print only failed logs with: + +```shell +gh run view <run-id> --repo apache/seatunnel --log-failed +``` + +## Classify the Failure + +| Log signal | Likely cause | Next action | +| --- | --- | --- | +| `COMPILATION ERROR`, `cannot find symbol`, `incompatible types`, or `method ... cannot be applied` | The queued commit does not compile with the latest `dev` | Fix the code or rebase the pull request | +| `Could not transfer artifact`, `Connection reset`, `Read timed out`, or an HTTP 403/429/5xx response | Maven repository or network failure | Confirm that no compilation error occurred, then requeue | +| The job reaches the 30-minute limit or is cancelled while a Maven step is still running | Runner, dependency download, or unexpectedly slow build | Check the last active step; investigate repeated timeouts before requeueing | +| No `Merge Queue` run starts, or the required `Build` remains pending until the queue timeout | Queue event, runner scheduling, or status-reporting problem | Check whether a `merge_group` run was created and whether the required check is linked to that run; preserve the pull request and run links for further investigation | +| The pull request timeline reports a base-branch conflict or branch-protection failure | The temporary commit no longer satisfies merge requirements | Update or rebase the pull request and complete the required checks again | + +## Recover and Requeue + +- For a code or compatibility failure, push the fix or rebase onto the latest `dev`. Wait for the pull-request checks and any required approval to pass again, then select **Merge when ready**. +- For a confirmed temporary infrastructure failure, select **Merge when ready** again without changing the code. +- Do not repeatedly requeue an unknown failure. Save the PR URL, workflow run URL, failed step, and the first relevant error when asking the community for help. +- Re-running an old workflow run does not add an ejected pull request back to the queue; requeue it from the pull request after the cause has been handled. + +If an earlier queue entry fails, GitHub rebuilds later temporary groups without that entry. No manual action is required for those later pull requests unless their own checks fail. + +## Last-resort Recovery When Merge Queue Remains Unavailable + +When Merge Queue itself fails and the troubleshooting and recovery steps above do not restore its ability to queue or merge an otherwise mergeable pull request, ASF Infra may use the `apache/root` team bypass as a last-resort recovery path. + +The bypass mode is `always`, so it applies to both pull-request merges and direct pushes for this ruleset; separate branch-protection rules are evaluated independently. + +:::warning Use only when normal recovery has failed + +This bypass is not an alternative merge path. It must not be used to skip normal queue waiting, required approval, a failed `Build`, or a compilation problem. + +Preserve the pull request and workflow-run links when contacting ASF Infra. Whenever possible, recovery should use a reviewed pull request with a successful normal `Build`; direct push should remain a last resort. + +Bypassing Merge Queue removes its exact-combination validation and may make active merge groups stale. After recovery, verify the new `dev` commit with the same Maven compile commands or an equivalent post-merge build, and monitor queued pull requests for automatic rebuilds or failures. + +::: diff --git a/docs/sidebars.js b/docs/sidebars.js index a986edc575..57c1fe4bd9 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -394,6 +394,7 @@ const sidebars = { "developer/setup", "developer/contribution-path", "developer/coding-guide", + "developer/merge-queue", "developer/test-coding-guide", "developer/shade-guide", "developer/how-to-create-your-connector", diff --git a/docs/zh/developer/merge-queue.md b/docs/zh/developer/merge-queue.md new file mode 100644 index 0000000000..4de96cd84a --- /dev/null +++ b/docs/zh/developer/merge-queue.md @@ -0,0 +1,66 @@ +# 使用 Merge Queue 合并 Pull Request + +SeaTunnel 对目标分支为 `dev` 的 Pull Request 启用了 [GitHub Merge Queue](https://docs.github.com/zh/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request-with-a-merge-queue)。队列会在合并前，基于最新的 `dev` 再次验证 PR。 + +## 将 Pull Request 加入队列 + +1. 确认 PR 已获得所需批准，并且 PR 自身的 `Build` 成功。 +2. 选择 **Merge when ready**。 +3. GitHub 会创建名称类似 `gh-readonly-queue/dev/pr-<number>-<sha>` 的临时分支。 +4. `Merge Queue` workflow 会对这个临时提交运行必需的 `Build`。 +5. 构建成功后，GitHub 会将 PR squash merge 到 `dev`。 + +队列构建首先使用 `ci` profile 编译标准 Maven reactor，然后使用 `benchmark` profile 编译 `seatunnel-benchmarks`。两个命令都使用 `-DskipTests`：测试不会执行，但 main 和 test 源码仍会编译。 + +## 查看 Pull Request 被移出队列的原因 + +必需检查失败或超时，或者临时提交与 `dev` 冲突时，GitHub 会将 PR 移出队列，并在 PR timeline 中记录原因。 + +1. 打开 PR，在 timeline 中找到被移出 Merge Queue 的事件。 +2. 通过失败的 `Build` 或 **Details** 链接进入 workflow run。 +3. 如果 timeline 中没有 run 链接，进入 `apache/seatunnel` 的 **Actions**，选择 **Merge Queue**，查找分支名包含 `pr-<PR编号>-` 的 run。 +4. 打开 `Build` job，并展开失败的步骤： + - `Compile main and test sources` + - `Compile benchmark main and test sources` +5. 在日志中搜索第一个 Maven `[ERROR]` 或 `BUILD FAILURE`。最后的 `Process completed with exit code 1` 只表示执行失败，真正的原因通常在它之前。 + +如果网页日志被截断或不方便搜索，可以在 run 页面选择 **Download log archive**。也可以使用 GitHub CLI 只查看失败日志： + +```shell +gh run view <run-id> --repo apache/seatunnel --log-failed +``` + +## 判断失败类型 + +| 日志特征 | 可能原因 | 处理方式 | +| --- | --- | --- | +| `COMPILATION ERROR`、`cannot find symbol`、`incompatible types` 或 `method ... cannot be applied` | 当前队列提交无法与最新 `dev` 一起编译 | 修复代码或对 PR 执行 rebase | +| `Could not transfer artifact`、`Connection reset`、`Read timed out` 或 HTTP 403/429/5xx | Maven 仓库或网络故障 | 确认没有编译错误后重新入队 | +| Job 达到 30 分钟限制，或者在 Maven 步骤仍在运行时被取消 | Runner、依赖下载或构建耗时异常 | 查看最后执行的步骤；重复超时时应先排查，不要直接重新入队 | +| 没有触发 `Merge Queue` run，或者必需的 `Build` 一直 pending 直到队列超时 | 队列事件、Runner 调度或状态上报异常 | 检查是否生成 `merge_group` run、required check 是否关联到该 run，并保留 PR 和 run 链接以便进一步排查 | +| PR timeline 提示与目标分支冲突或分支保护失败 | 临时提交不再满足合并要求 | 更新或 rebase PR，并重新完成必需检查 | + +## 修复并重新入队 + +- 如果是代码或兼容性问题，请提交修复或基于最新 `dev` 执行 rebase。等待 PR 检查和所需批准再次通过后，选择 **Merge when ready**。 +- 如果已经确认是临时基础设施故障，可以不修改代码，直接再次选择 **Merge when ready**。 +- 不要对原因不明的失败反复重新入队。向社区求助时，请提供 PR URL、workflow run URL、失败步骤和第一个有效错误。 +- 重新运行旧的 workflow run 不会让已被移出的 PR 重新进入队列；处理完失败原因后，需要回到 PR 页面重新入队。 + +如果较早的队列条目失败，GitHub 会排除该条目并重新构建后续临时 merge group。除非后续 PR 自身的检查也失败，否则不需要人工处理。 + +## Merge Queue 无法恢复时的应急处理 + +当 Merge Queue 本身发生故障，并且按照上述排查和恢复步骤处理后，仍然无法让一个原本满足合并条件的 PR 正常入队或合并时，ASF Infra 可以使用 `apache/root` team 的 bypass 作为最后恢复手段。 + +bypass mode 为 `always`，因此对该 Ruleset 的 Pull Request 合并和直接 push 均适用；其他独立的分支保护规则仍会分别检查。 + +:::warning 仅在常规恢复无效时使用 + +此 bypass 不是另一种日常合并方式。不得用它跳过正常排队、必需的批准、失败的 `Build` 或编译问题。 + +联系 ASF Infra 时，请保留 PR 和 workflow run 链接。只要条件允许，应通过已经 review 且普通 `Build` 成功的 PR 完成恢复；直接 push 只能作为最后手段。 + +绕过 Merge Queue 会失去最终代码组合验证，也可能让正在运行的 merge group 失效。恢复后，应使用相同的 Maven 编译命令或等价的 post-merge build 验证新的 `dev` 提交，并关注队列中的 PR 是否自动重新构建或失败。 + +:::
