workflow: check TiDB code PRs weekly to update docs

.github/workflows/tidb-pr-weekly-doc-check.yml

@@ -0,0 +1,154 @@
+name: Weekly PingCAP Code PR Doc Check (docs-cn)
+
+on:
+  schedule:
+    # 01:00 every Monday in Asia/Shanghai (UTC+8) => 17:00 every Sunday UTC
+    - cron: "0 17 * * 0"
+  workflow_dispatch:
+
+jobs:
+  scan:
+    if: github.repository == 'pingcap/docs'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    outputs:
+      needs_update: ${{ steps.scan.outputs.needs_update }}
+      candidates_count: ${{ steps.scan.outputs.candidates_count }}
+      candidates_matrix: ${{ steps.scan.outputs.candidates_matrix }}
+      json_path: ${{ steps.scan.outputs.json_path }}
+      report_path: ${{ steps.scan.outputs.report_path }}
+      window_start_date: ${{ steps.scan.outputs.window_start_date }}
+      window_end_date: ${{ steps.scan.outputs.window_end_date }}
+    env:
+      SOURCE_ORG: pingcap
+      EXCLUDED_REPOS: pingcap/docs,pingcap/docs-cn
+      EXTRA_REPOS: tikv/tikv,tikv/pd
+      OUTPUT_DIR: tmp/tidb-doc-check
+      DOCS_CN_BASE_BRANCH: master
+      TARGET_BRANCH_MAP: '{"master":"master","release-8.5":"release-8.5","release-8.1":"release-8.1","release-7.5":"release-7.5","release-7.1":"release-7.1","release-6.5":"release-6.5","release-6.1":"release-6.1","release-5.4":"release-5.4"}'
+    steps:
+      - name: Checkout docs repo
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Scan merged PingCAP code PRs in last weekly window
+        id: scan
+        env:
+          GITHUB_TOKEN: ${{ secrets.DOCS_CN_BOT_TOKEN || github.token }}
+          SOURCE_ORG: ${{ env.SOURCE_ORG }}
+          EXCLUDED_REPOS: ${{ env.EXCLUDED_REPOS }}
+          EXTRA_REPOS: ${{ env.EXTRA_REPOS }}
+          OUTPUT_DIR: ${{ env.OUTPUT_DIR }}
+          DOCS_CN_BASE_BRANCH: ${{ env.DOCS_CN_BASE_BRANCH }}
+          TARGET_BRANCH_MAP: ${{ env.TARGET_BRANCH_MAP }}
+        run: |
+          set -euo pipefail
+          python scripts/check_tidb_prs_and_create_docs_cn_pr.py
+
+      - name: Print summary
+        run: |
+          echo "needs_update=${{ steps.scan.outputs.needs_update }}"
+          echo "candidates_count=${{ steps.scan.outputs.candidates_count }}"
+
+      - name: Upload scan artifacts
+        if: steps.scan.outputs.needs_update == 'true'
+        uses: actions/upload-artifact@v4
+        with:
+          name: weekly-doc-check-report
+          path: |
+            ${{ steps.scan.outputs.json_path }}
+            ${{ steps.scan.outputs.report_path }}
+
+  create-pr-per-source:
+    if: needs.scan.outputs.needs_update == 'true'
+    needs: scan
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      max-parallel: 4
+      matrix: ${{ fromJson(needs.scan.outputs.candidates_matrix) }}
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout docs repo
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Download scan artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: weekly-doc-check-report
+          path: tmp/tidb-doc-check
+
+      - name: Checkout docs-cn repo target branch
+        uses: actions/checkout@v4
+        with:
+          repository: pingcap/docs-cn
+          token: ${{ secrets.DOCS_CN_BOT_TOKEN }}
+          ref: ${{ matrix.target_branch }}
+          path: docs-cn
+          persist-credentials: false
+
+      - name: Apply docs-cn updates for one source PR
+        run: |
+          set -euo pipefail
+          python scripts/apply_weekly_docs_cn_updates.py \
+            --report-json "$(ls tmp/tidb-doc-check/*.json | head -1)" \
+            --docs-cn-dir "docs-cn" \
+            --source-repo "${{ matrix.repo }}" \
+            --source-pr-number "${{ matrix.number }}"
+
+      - name: Build branch metadata
+        id: meta
+        shell: bash
+        run: |
+          set -euo pipefail
+          safe_repo="$(echo "${{ matrix.repo }}" | tr '/' '-')"
+          echo "safe_repo=${safe_repo}" >> "$GITHUB_OUTPUT"
+          echo "branch=weekly/doc-sync/${safe_repo}-pr-${{ matrix.number }}-${{ needs.scan.outputs.window_end_date }}" >> "$GITHUB_OUTPUT"
+
+      - name: Create docs-cn PR for one source PR
+        uses: peter-evans/create-pull-request@v7
+        with:
+          path: docs-cn
+          token: ${{ secrets.DOCS_CN_BOT_TOKEN }}
+          branch: ${{ steps.meta.outputs.branch }}
+          base: ${{ matrix.target_branch }}
+          commit-message: "docs: sync from ${{ matrix.repo }}#${{ matrix.number }}"
+          title: "docs: sync from ${{ matrix.repo }}#${{ matrix.number }}"
+          body: |
+            ### What is changed, added or deleted? (Required)
+
+            Sync docs-cn updates for one source code PR.
+
+            - Source PR: ${{ matrix.url }}
+            - Source repo: `${{ matrix.repo }}`
+            - Source PR number: `${{ matrix.number }}`
+            - Source base branch: `${{ matrix.source_base_branch }}`
+            - Target docs-cn branch: `${{ matrix.target_branch }}`
+            - Weekly window (Asia/Shanghai): `${{ needs.scan.outputs.window_start_date }} 00:00` to `${{ needs.scan.outputs.window_end_date }} 00:00`
+
+            ### Which TiDB version(s) do your changes apply to? (Required)
+
+            - [x] ${{ matrix.target_branch }}
+
+            ### What is the related PR or file link(s)?
+
+            - This PR is translated from: ${{ matrix.url }}
+
+            ### Do your changes match any of the following descriptions?
+
+            - [ ] Delete files
+            - [ ] Change aliases
+            - [ ] Need modification after applied to another branch
+            - [ ] Might cause conflicts after applied to another branch
+          delete-branch: true

scripts/apply_weekly_docs_cn_updates.py

@@ -0,0 +1,115 @@
+#!/usr/bin/env python3
+"""Apply docs-cn updates for one source PR candidate."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import pathlib
+from typing import Dict, List
+
+
+PATH_TO_DOCS = {
+    "pkg/sessionctx/variable/": ["system-variables.md"],
+    "pkg/config/": ["tidb-configuration-file.md"],
+    "pkg/parser/": ["sql-statements/sql-statement-overview.md"],
+    "pkg/ddl/": ["ddl-introduction.md"],
+    "pkg/planner/": ["sql-optimization-concepts.md"],
+    "pkg/executor/": ["sql-optimization-concepts.md"],
+    "br/": ["br/backup-and-restore-overview.md"],
+    "lightning/": ["tidb-lightning/tidb-lightning-overview.md"],
+    "dumpling/": ["dumpling-overview.md"],
+}
+
+REPO_TO_DOCS = {
+    "pingcap/tiflow": ["ticdc/ticdc-overview.md"],
+    "pingcap/tikv": ["tikv-overview.md"],
+    "pingcap/pd": ["pd-overview.md"],
+    "pingcap/tidb-binlog": ["tidb-binlog/tidb-binlog-overview.md"],
+    "pingcap/tiup": ["tiup/tiup-overview.md"],
+}
+
+
+def resolve_target_docs(repo: str, changed_files: List[str]) -> List[str]:
+    targets = set(REPO_TO_DOCS.get(repo, []))
+    for file_path in changed_files:
+        for prefix, docs_list in PATH_TO_DOCS.items():
+            if file_path.startswith(prefix):
+                targets.update(docs_list)
+    return sorted(targets)
+
+
+def append_pr_note(file_path: pathlib.Path, marker: str, lines: List[str]) -> bool:
+    if not file_path.exists():
+        return False
+    content = file_path.read_text(encoding="utf-8")
+    if marker in content:
+        return False
+    block = ["", marker, "## Weekly code sync note", ""]
+    block.extend(lines)
+    block.append("")
+    file_path.write_text(content.rstrip() + "\n" + "\n".join(block), encoding="utf-8")
+    return True
+
+
+def load_candidate(report: Dict, repo: str, number: int) -> Dict:
+    for pr in report.get("pull_requests", []):
+        if pr.get("repo") == repo and int(pr.get("number", -1)) == number:
+            return pr
+    raise SystemExit(f"Candidate not found in report: {repo}#{number}")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--report-json", required=True)
+    parser.add_argument("--docs-cn-dir", required=True)
+    parser.add_argument("--source-repo", required=True)
+    parser.add_argument("--source-pr-number", required=True, type=int)
+    args = parser.parse_args()
+
+    report_json = pathlib.Path(args.report_json).resolve()
+    docs_cn_dir = pathlib.Path(args.docs_cn_dir).resolve()
+    payload = json.loads(report_json.read_text(encoding="utf-8"))
+    pr = load_candidate(payload, args.source_repo, args.source_pr_number)
+
+    if not pr.get("needs_docs_update"):
+        return
+
+    targets = resolve_target_docs(pr.get("repo", ""), pr.get("changed_files", []))
+    marker = f"<!-- weekly-code-sync: {pr['repo']}#{pr['number']} -->"
+    note_lines = [
+        f"- Source PR: [{pr['repo']}#{pr['number']}]({pr['url']})",
+        f"- Title: {pr['title']}",
+        f"- Merged at: `{pr['merged_at']}`",
+        f"- Reasons: {'; '.join(pr.get('reasons', []))}",
+    ]
+
+    changed_files: List[str] = []
+    missing_files: List[str] = []
+    for rel_path in targets:
+        abs_path = docs_cn_dir / rel_path
+        changed = append_pr_note(abs_path, marker, note_lines)
+        if changed:
+            changed_files.append(rel_path)
+        elif not abs_path.exists():
+            missing_files.append(rel_path)
+
+    out_dir = docs_cn_dir / "weekly-doc-sync"
+    out_dir.mkdir(parents=True, exist_ok=True)
+    summary_path = out_dir / f"applied-{pr['repo'].replace('/', '_')}-{pr['number']}.json"
+    summary = {
+        "source_repo": pr["repo"],
+        "source_pr_number": pr["number"],
+        "target_docs_files": targets,
+        "changed_docs_files": changed_files,
+        "missing_mapped_files": sorted(set(missing_files)),
+    }
+    summary_path.write_text(json.dumps(summary, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+
+    print(f"Changed docs files for {pr['repo']}#{pr['number']}:")
+    for item in changed_files:
+        print(f"- {item}")
+
+
+if __name__ == "__main__":
+    main()