docs/docs-cn: simplify pull_verify pipeline

[qiancai]

What problem does this PR solve?

The current pingcap/docs and pingcap/docs-cn pull_verify pipelines use a 6-leg matrix where each leg spins up its own pod and repeats the same heavy setup work:

• schedule a separate Kubernetes pod
• restore / checkout the docs repository
• prepare the same helper scripts again
• run one lightweight check on the changed .md files

In practice, the bottleneck is usually pod readiness and repeated setup, not the checks themselves.

A concrete example is pingcap/docs PR #22748:

• pull_verify build #19043 was aborted after about 15m35s
• a later successful rerun #19047 still took about 13m58s

Another recent example is pingcap/docs PR #22753, where successful build #19024 took about 20m44s.

For these small docs-only PRs, the actual checks are cheap because they only run against files from git diff-tree; the repeated matrix setup dominates the runtime.

What is changed?

This PR simplifies both pingcap/docs and pingcap/docs-cn pull_verify pipelines from a 6-leg matrix into a single-pod sequential flow:

1. Checkout
   • run prow.checkoutRefsWithCacheLock(REFS) only once
2. Prepare
   • download the five helper scripts from pingcap/docs/master only once
3. Verify
   • compute the changed markdown file list once
   • skip quickly when there are no changed .md files
   • run all 6 checks sequentially in the same pod
   • aggregate failures so one run can report multiple failing checks instead of stopping at the first failure

This keeps the existing validation scope, required context, and trigger model unchanged. The main difference is that we remove repeated pod scheduling, repeated checkout/cache restore, and repeated helper-script preparation.

Expected impact

Based on recent pull_verify runs, the current matrix-based flow commonly spends around 14-21 minutes even on relatively small docs PRs.

With this change, the expected runtime for typical small or medium docs PRs should drop to roughly 2-5 minutes:

• 1 pod startup instead of up to 6 separate pod startups
• 1 checkout / cache restore instead of 6 repeated checkouts
• 1 helper-script preparation step instead of 6 repeated preparations
• the 6 checks themselves still run, but they are lightweight and operate only on changed markdown files

The exact savings still depend on Kubernetes scheduling and network conditions, but this should remove the largest fixed-cost duplication in the current design.

Validation

• JENKINS_URL=https://do.pingcap.net/jenkins .ci/verify-jenkins-pipeline-file.sh pipelines/pingcap/docs/latest/pull_verify.groovy
• JENKINS_URL=https://do.pingcap.net/jenkins .ci/verify-jenkins-pipeline-file.sh pipelines/pingcap/docs-cn/latest/pull_verify.groovy

[ti-chi-bot]

Hi @qiancai. Thanks for your PR.

I'm waiting for a PingCAP-QE member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[gemini-code-assist]

Code Review

This pull request refactors the pull_verify.groovy pipelines for both the docs-cn and docs repositories, transitioning from a matrix-based execution to a sequential stage-based model. The new structure includes explicit stages for checking out code, preparing check scripts via wget, and a comprehensive verification stage that runs multiple Python-based checks and markdownlint. Feedback suggests that for better CI reliability and performance, the check scripts should be baked into the Docker image rather than being downloaded and managed at runtime.

[gemini-code-assist]

Instead of managing check scripts at runtime by copying them or referencing sibling directories, these scripts should be baked into the Docker image. This approach improves CI reliability and performance by ensuring a consistent environment and reducing runtime overhead, consistent with repository practices.

                    failed_checks=()

                    run_check() {
                        local name="\$1"
                        shift

                        echo "==> Running \${name}"
                        if "\$@" "\${diff_docs_files[@]}"; then
                            echo "==> \${name}: PASS"
                        else
                            echo "==> \${name}: FAIL"
                            failed_checks+=("\${name}")
                        fi
                        echo
                    }

                    run_check 'check-file-encoding' python3 /usr/local/bin/check-file-encoding.py
                    run_check 'check-conflicts' python3 /usr/local/bin/check-conflicts.py
                    run_check 'check-control-char' python3 /usr/local/bin/check-control-char.py
                    run_check 'check-tags' python3 /usr/local/bin/check-tags.py
                    run_check 'check-manual-line-breaks' python3 /usr/local/bin/check-manual-line-breaks.py

References

1. For better CI performance and reliability, bake dependencies into the Docker image instead of installing them at runtime in CI scripts.

[gemini-code-assist]

Instead of managing check scripts at runtime by copying them or referencing sibling directories, these scripts should be baked into the Docker image. This approach improves CI reliability and performance by ensuring a consistent environment and reducing runtime overhead, consistent with repository practices.

                    failed_checks=()

                    run_check() {
                        local name="\$1"
                        shift

                        echo "==> Running \${name}"
                        if "\$@" "\${diff_docs_files[@]}"; then
                            echo "==> \${name}: PASS"
                        else
                            echo "==> \${name}: FAIL"
                            failed_checks+=("\${name}")
                        fi
                        echo
                    }

                    run_check 'check-file-encoding' python3 /usr/local/bin/check-file-encoding.py
                    run_check 'check-conflicts' python3 /usr/local/bin/check-conflicts.py
                    run_check 'check-control-char' python3 /usr/local/bin/check-control-char.py
                    run_check 'check-tags' python3 /usr/local/bin/check-tags.py
                    run_check 'check-manual-line-breaks' python3 /usr/local/bin/check-manual-line-breaks.py

References

1. For better CI performance and reliability, bake dependencies into the Docker image instead of installing them at runtime in CI scripts.

[wuhuizuo]

/ok-to-test

[ti-chi-bot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: wuhuizuo

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details

Needs approval from an approver in each of these files:

• pipelines/pingcap/docs/OWNERS [wuhuizuo]
• pipelines/pingcap/docs-cn/OWNERS [wuhuizuo]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[wuhuizuo]

/hold

[ti-chi-bot]

[LGTM Timeline notifier]

Timeline:

• 2026-04-16 10:07:10.095284012 +0000 UTC m=+1642035.300644079: ☑️ agreed by wuhuizuo.
• 2026-04-16 10:18:51.780280245 +0000 UTC m=+1642736.985640302: ✖️🔁 reset by qiancai.

[ti-chi-bot]

New changes are detected. LGTM label has been removed.