Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 12 additions & 3 deletions .github/workflows/release-checks.yml
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,10 @@ jobs:
if: inputs.static-checks
runs-on: ubuntu-22.04
timeout-minutes: 10
outputs:
run-heavy: ${{ steps.scope.outputs.run-heavy }}
scope-reason: ${{ steps.scope.outputs.scope-reason }}
changed-files: ${{ steps.scope.outputs.changed-files }}
steps:
- uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
with:
Expand All @@ -47,10 +51,15 @@ jobs:
else
python -m pre_commit run --all-files
fi
- id: scope
name: Select check scope / 判断检查范围
env:
PR_BASE_SHA: ${{ github.event.pull_request.base.sha }}
run: python scripts/ci/select_checks.py

python:
needs: static
if: ${{ !cancelled() && (needs.static.result == 'success' || (!inputs.static-checks && needs.static.result == 'skipped')) }}
if: ${{ !cancelled() && ((needs.static.result == 'success' && needs.static.outputs.run-heavy != 'false') || (!inputs.static-checks && needs.static.result == 'skipped')) }}
runs-on: ubuntu-22.04
timeout-minutes: 30
steps:
Expand Down Expand Up @@ -114,7 +123,7 @@ jobs:

frontend:
needs: static
if: ${{ !cancelled() && (needs.static.result == 'success' || (!inputs.static-checks && needs.static.result == 'skipped')) }}
if: ${{ !cancelled() && ((needs.static.result == 'success' && needs.static.outputs.run-heavy != 'false') || (!inputs.static-checks && needs.static.result == 'skipped')) }}
runs-on: ubuntu-22.04
timeout-minutes: 30
steps:
Expand Down Expand Up @@ -171,7 +180,7 @@ jobs:

browser:
needs: static
if: ${{ !cancelled() && (needs.static.result == 'success' || (!inputs.static-checks && needs.static.result == 'skipped')) }}
if: ${{ !cancelled() && ((needs.static.result == 'success' && needs.static.outputs.run-heavy != 'false') || (!inputs.static-checks && needs.static.result == 'skipped')) }}
runs-on: ubuntu-22.04
timeout-minutes: 30
strategy:
Expand Down
22 changes: 13 additions & 9 deletions docs/development/validation.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ This is the target contract for [#273](https://github.com/ThinkFlowLab/OpenDirec
| Stage / 阶段 | Trigger / 触发 | Responsibility / 职责 | Target budget / 目标预算 |
| --- | --- | --- | --- |
| Local / 本地 | Before commit and PR creation / 提交及提出 PR 前 | One `.pre-commit-config.yaml` for staged-file hooks and an explicit whole-PR diff check, shared by users and agents. No ready tests. / 同一配置用于暂存文件 hook 和覆盖整个 PR 差异的显式检查,用户与 agent 共用;不跑 ready。 | Fast static feedback; measure warm runs separately from setup / 快速静态反馈,暖运行与初始化分别计时 |
| PR | Open, reopen and update, including drafts / 提出、重开及更新,包含 draft | CI repeats the same static configuration before ready: frontend units, Python ready, i18n, browser locale/manifest, imports, generated contracts, production build, wheel verification and browser gate including voice and assistant auxiliary panels. Every PR also runs security scanning. / 静态复核通过后跑 ready:前端单元、Python ready、国际化、浏览器语言与清单、分层导入、生成契约、构建、wheel 和包含语音及助手辅助面板的浏览器 gate;每个 PR 另跑安全扫描。 | Entire PR gate ≤15 min / 整个 PR 门禁 ≤15 分钟 |
| PR | Open, reopen and update, including drafts / 提出、重开及更新,包含 draft | CI repeats the same static configuration before ready: frontend units, Python ready, i18n, browser locale/manifest, imports, generated contracts, production build, wheel verification and browser gate including voice and assistant auxiliary panels. Every PR also runs security scanning. / 静态复核通过后跑 ready:前端单元、Python ready、国际化、浏览器语言与清单、分层导入、生成契约、构建、wheel 和包含语音及助手辅助面板的浏览器 gate;每个 PR 另跑安全扫描。 | Entire PR gate ≤30 min / 整个 PR 门禁 ≤30 分钟 |
| Merge queue / 合并队列 | `merge_group: checks_requested`, before main changes / main 更新前 | Test latest main plus preceding queued PRs and this PR. Repeat PR checks and add Python merge; all required checks must succeed before merging. / 验证最新 main、前序排队 PR 与当前 PR 的组合;复跑 PR 检查并增加 Python merge,必需检查全部成功后才能合入。 | Entire queue gate ≤30 min / 整个队列门禁 ≤30 分钟 |
| main | Push after successful queue merge / 队列成功合并后的 push | Collect merged SHA, successful queue checks and artifacts; prove they correspond to merged content. No routine full-suite rerun. Missing or unprovable evidence blocks release and requires checks on the exact main SHA. / 归集合并 SHA、成功队列检查与产物,证明其对应合并内容;常规不重跑完整套件。证据缺失或无法对应时阻止发布,对准确 main SHA 补跑。 | Evidence collection / 证据归集 |
| Nightly / 夜间 | `0 18 * * *` UTC, next day 02:00 Asia/Shanghai; manual dispatch / 定时或手动 | Python nightly, flake watchlist, browser extended/extendedFixture, production, perf and daily benchmark. Advisory failures are tracked; no automatic tags. Do not repeat PR/queue suites except intentional watchlist reruns. / 运行 Python nightly、flake watchlist、浏览器扩展与独立 fixture、生产、性能及每日基准;advisory 失败须跟踪,不自动打 tag;除明确的 watchlist 重跑外,不重复 PR/队列套件。 | Extended ≤60; production ≤45; perf and benchmark each ≤30 min / 扩展 ≤60、生产 ≤45、性能与基准各 ≤30 分钟 |
Expand All @@ -53,9 +53,9 @@ Budgets measure stage wall time, not the sum of parallel job limits, and never j

### 过渡与必需检查 / Transition and required checks

当前 [`ci.yml`](../../.github/workflows/ci.yml) 对 PR 和 main push 开启静态门禁,Python 仍跑全量;[`nightly.yml`](../../.github/workflows/nightly.yml) 保留 gate-parity 和全量 Python flake 分诊。已注册 CI 层 mark,但机型轴、安全扫描、docs-only 重任务跳过、合并队列与 main 证据归集仍是后续交付。当前 job 限额见下方静态检查说明;15/30 分钟是目标阶段预算,不代表当前已强制执行。
当前 [`ci.yml`](../../.github/workflows/ci.yml) 对 PR 和 main push 开启静态门禁;纯文档 PR 按下方白名单跳过重检查,其余仍跑全量 Python。[`nightly.yml`](../../.github/workflows/nightly.yml) 保留 gate-parity 和全量 Python flake 分诊。已注册 CI 层 mark,但机型轴、安全扫描、合并队列与 main 证据归集仍是后续交付。当前 job 限额见下方静态检查说明;PR 和队列各 30 分钟是阶段目标,不代表已强制端到端总上限。

Currently [`ci.yml`](../../.github/workflows/ci.yml) enables static checks on PRs and main pushes while Python still runs in full. [`nightly.yml`](../../.github/workflows/nightly.yml) retains gate parity and full-suite Python flake triage. CI-layer marks are registered; hardware tagging, security scanning, docs-only heavy-job skipping, the merge queue and main evidence collection remain follow-up delivery. Current job limits are documented below; the 15/30-minute stage budgets are targets, not existing enforcement.
Currently [`ci.yml`](../../.github/workflows/ci.yml) enables static checks on PRs and main pushes. Documentation-only PRs use the allowlist below to skip heavy checks; other changes retain full Python selection. [`nightly.yml`](../../.github/workflows/nightly.yml) retains gate parity and full-suite Python flake triage. CI-layer marks are registered; hardware tagging, security scanning, the merge queue and main evidence collection remain follow-up delivery. Current job limits are documented below; 30 minutes each for PR and queue are stage targets, not enforced end-to-end deadlines.

- 本地 hook 可未安装或被绕过,不能在 GitHub 上普遍阻止 PR 创建。必需 CI 必须复核同一配置;静态失败阻止启动重测试,并使稳定汇总检查失败。/ Local hooks can be absent or bypassed and cannot universally prevent PR creation. Required CI repeats the same configuration; static failure blocks heavy jobs and fails the stable aggregate.
- 纯文档变更可跳过重 Python/浏览器任务,但必须保留稳定的必需检查,报告跳过依据并成功结束。合并队列按整个 merge-group 差异判断,不能只看最后一个 PR;无法确定范围时执行完整门禁。/ Documentation-only changes may skip heavy Python/browser jobs, but a stable required check must report the reason and succeed. Queue filtering covers the whole merge-group diff, not only its last PR; uncertain scope runs the full gate.
Expand Down Expand Up @@ -102,17 +102,21 @@ Checks cover YAML/JSON/TOML and Python syntax, conflict markers, Python debug st

Local hooks can be absent or bypassed. PR and main Release checks run the same configuration in a separate static job. PRs compare base to tested merge HEAD; pushes compare before to HEAD. Only the static checkout needing a range comparison fetches full history; other jobs use shallow checkouts. Manual/initial-push full-file audits do not need full history.

静态通过后并行运行 Python(导入、契约、全量 pytest、bundled OpenCode 回归)、前端/构建/wheel 和浏览器检查。浏览器 isolated、voice、assistant 分为三个独立 matrix job,`fail-fast: false`,一条失败不取消其余旅程。每个 runner 独立安装依赖,复用现有 pip/npm 缓存;这会增加 runner 分钟数,墙钟耗时改善须以实际 CI 为准。
静态通过后,范围检查仅对 PR 比较 base 与测试用合并 HEAD 的 merge-base 差异,保留整个 PR 的变更。只有非空差异全部属于根目录 `README.md`、`README.zh-CN.md`、`CONTRIBUTING.md`、`CHANGELOG.md`,或 `docs/` 内的 Markdown、PNG/JPEG/GIF/WebP,才跳过 Python、前端/构建/wheel 和全部 browser matrix。重命名同时检查旧、新路径;文档目录内的代码/配置、AGENTS/skill、工作流、测试、混合变更、空差异或比较失败都跑完整门禁。分类不会访问 PR API,路径使用 NUL 分隔,含空格或中文不会截断。

After static success, Python (imports, contracts, full pytest and bundled OpenCode), frontend/build/wheel and browser checks run in parallel. Browser isolated, voice and assistant journeys use separate matrix jobs with fail-fast disabled. Each runner installs its own dependencies using existing pip/npm caches. This increases runner minutes; wall-clock improvements require actual CI measurements.
After static success, scope selection compares the PR base and tested merge HEAD from their merge base, retaining the whole PR diff. Heavy Python, frontend/build/wheel and all browser matrix jobs are skipped only for a nonempty diff entirely within root `README.md`, `README.zh-CN.md`, `CONTRIBUTING.md`, `CHANGELOG.md`, or Markdown/PNG/JPEG/GIF/WebP under `docs/`. Renames check both old and new paths. Code/configuration under docs, AGENTS/skills, workflows, tests, mixed changes, empty diffs and unavailable comparisons keep the full gate. Selection needs no PR API; NUL-delimited paths preserve spaces and non-ASCII names.

最终 `checks` 汇总 job 保留现有必需检查名称,并始终读取各检查线结果;任何失败、取消、意外跳过或缺失回执均失败。只有调用方显式关闭静态检查时,static 的 skipped 才允许通过。静态失败不会启动重测试,但最终汇总仍失败,不能把依赖跳过误判为通过。
main push、手动运行和 nightly 保持完整检查;本次不启用 `merge_group`,也不切换 Python ready 筛选。需要重检查时,Python(导入、契约、全量 pytest、bundled OpenCode)、前端/构建/wheel 和浏览器并行执行,browser `fail-fast: false`;一条失败不取消其余旅程。

The final `checks` aggregate preserves the existing required-check name and always evaluates all lane results. Failure, cancellation, unexpected skips or missing receipts fail closed. A skipped static job is allowed only when the caller explicitly disabled static checks. Static failure prevents heavy test jobs from starting and still fails the aggregate.
Main pushes, manual runs and nightly retain full checks. This change enables neither `merge_group` nor Python ready selection. When heavy checks are required, Python (imports, contracts, full pytest and bundled OpenCode), frontend/build/wheel and browser jobs run in parallel with browser fail-fast disabled; one failure does not cancel other journeys.

可复用工作流的 `static-checks` 默认关闭,由 `ci.yml` 开启;nightly 不新增重复静态检查。CI 不提交自动修复:hook 修改文件视为失败,需在本地修复。当前静态 job 上限 10 分钟,Python、前端和每个浏览器 job 各 30 分钟,汇总 job 5 分钟;这是各 job 的限额,不是整个工作流的总上限。当前仍跑全量,暂不采用 PR ready 子集的 15 分钟目标;待子集切换或并行运行有足够耗时证据后再收紧。
最终 `checks` 汇总保留现有必需检查名称并始终执行。只有 static 成功且提供明确的 `docs_only`、正数变更路径数、PR 事件和跳过决定时,才接受三条重检查线的 skipped;汇总会报告依据。任何失败、取消、意外跳过、无效决定或缺失回执仍失败。只有调用方显式关闭静态检查时,static 自身才允许 skipped,且此时必须跑重检查。静态失败造成的依赖跳过不能通过汇总。

The reusable workflow's `static-checks` defaults to false and is enabled by `ci.yml`; nightly adds no duplicate static pass. CI never commits automatic fixes. Static has a 10-minute timeout; Python, frontend and each browser job have 30 minutes; the aggregate has 5 minutes. These are per-job limits, not a workflow-wide deadline. Full suites still run, so the 15-minute PR-ready target is deferred until subset activation or sufficient timing evidence from parallel runs.
The final `checks` aggregate preserves its required-check name and always runs. Only successful static checks with an explicit `docs_only` decision, a positive changed-path count and a PR event can authorize skipped heavy lanes; the summary reports that evidence. Failures, cancellations, unexpected skips, invalid decisions and missing receipts still fail. Only an explicitly disabled static lane may itself be skipped, in which case heavy lanes must run. Dependency skips after static failure cannot pass the aggregate.

可复用工作流的 `static-checks` 默认关闭,由 `ci.yml` 开启;nightly 不重复静态检查。CI 不提交自动修复,hook 修改文件仍视为失败。PR 阶段预算先按 30 分钟;当前 static 上限 10 分钟,Python、前端和每个浏览器 job 各 30 分钟,汇总 5 分钟。这些仍是各 job 限额,不能相加或解释为已强制的阶段总上限;后续按实际测量改进端到端耗时。

The reusable workflow's `static-checks` defaults to false and is enabled by `ci.yml`; nightly does not duplicate static checks. CI never commits automatic fixes; hook edits remain failures. The PR stage budget is 30 minutes for now. Static has 10 minutes, Python/frontend/each browser job 30 minutes, and the aggregate 5 minutes. These remain per-job limits, not a summed or enforced workflow-wide deadline; improve end-to-end time using actual measurements.

## Python 分层与迁移 / Python layers and transition

Expand Down
70 changes: 70 additions & 0 deletions scripts/ci/select_checks.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
"""Skip heavy PR checks only for a proven, nonempty documentation-only diff."""
import json
import os
from pathlib import Path, PurePosixPath
import re
import subprocess


ROOT_DOCUMENTS = {'README.md', 'README.zh-CN.md', 'CONTRIBUTING.md', 'CHANGELOG.md'}
DOCUMENT_SUFFIXES = {'.md', '.png', '.jpg', '.jpeg', '.gif', '.webp'}
REASONS = {
'docs_only': 'Documentation only; heavy checks skipped / 纯文档,跳过重检查',
'non_documentation': 'Code, configuration or other inputs changed / 代码、配置或其他输入有变更',
'comparison_unavailable': 'Diff could not be proven; run full checks / 无法确认差异,运行完整检查',
'empty_diff': 'Empty diff; run full checks / 差异为空,运行完整检查',
'event_requires_full': 'Only pull requests may skip heavy checks / 仅 PR 可跳过重检查',
}


def documentation(path):
if path in ROOT_DOCUMENTS:
return True
if not path.startswith('docs/') or '\\' in path or any(part in {'', '.', '..'} for part in path.split('/')):
return False
return PurePosixPath(path).suffix.lower() in DOCUMENT_SUFFIXES


def select(event, base, *, repository=None):
result = {'run-heavy': 'true', 'scope-reason': 'event_requires_full', 'changed-files': '0'}
if event != 'pull_request':
return result
result['scope-reason'] = 'comparison_unavailable'
if not re.fullmatch(r'[0-9a-f]{40}', base or ''):
return result
try:
# Three dots match the pre-commit PR range. Disabling rename detection
# retains both old and new paths: code renamed into docs is still code.
diff = subprocess.check_output(
['git', 'diff', '--no-ext-diff', '--no-renames', '--name-only', '-z', base + '...HEAD', '--'],
cwd=repository, stderr=subprocess.DEVNULL, timeout=30,
)
if diff and not diff.endswith(b'\0'):
return result
paths = diff.decode('utf-8').rstrip('\0').split('\0') if diff else []
except (OSError, subprocess.SubprocessError, UnicodeError):
return result
result['changed-files'] = str(len(paths))
if not paths:
result['scope-reason'] = 'empty_diff'
elif all(documentation(path) for path in paths):
result.update({'run-heavy': 'false', 'scope-reason': 'docs_only'})
else:
result['scope-reason'] = 'non_documentation'
return result


def main():
result = select(os.environ.get('GITHUB_EVENT_NAME'), os.environ.get('PR_BASE_SHA'))
print(json.dumps(result))
if path := os.environ.get('GITHUB_OUTPUT'):
with Path(path).open('a', encoding='utf-8') as output:
output.writelines(f'{key}={value}\n' for key, value in result.items())
if path := os.environ.get('GITHUB_STEP_SUMMARY'):
with Path(path).open('a', encoding='utf-8') as output:
output.write('## Check scope / 检查范围\n\n' + REASONS[result['scope-reason']]
+ '\n\nChanged paths / 变更路径数: ' + result['changed-files'] + '\n')


if __name__ == '__main__':
main()
Loading
Loading