diff --git a/.github/ISSUE_TEMPLATE/work_item.yml b/.github/ISSUE_TEMPLATE/work_item.yml index 403df3b12..d15d8a6aa 100644 --- a/.github/ISSUE_TEMPLATE/work_item.yml +++ b/.github/ISSUE_TEMPLATE/work_item.yml @@ -4,6 +4,18 @@ title: "Work: " labels: - enhancement body: + - type: dropdown + id: scope_level + attributes: + label: Scope level + description: Choose roadmap for an integrated outcome delivered through multiple child PRs; choose implementation for one cohesive review unit. + options: + - implementation + - roadmap + - research + validations: + required: true + - type: dropdown id: work_type attributes: @@ -50,7 +62,7 @@ body: id: deliverable attributes: label: Deliverable - description: What concrete output is expected? + description: What cohesive, reviewable output is expected? Include the code, config, tests, and docs needed to make that result complete. placeholder: | Examples: - merged code @@ -60,13 +72,34 @@ body: validations: required: true + - type: textarea + id: scope + attributes: + label: Scope and delivery boundaries + description: Describe the work kept together for this outcome and the independently valuable work tracked elsewhere. + placeholder: | + In this work item: + - ... + + Related follow-up or separate outcomes: + - ... + validations: + required: true + + - type: textarea + id: roadmap + attributes: + label: Roadmap relationship and target branch + description: For a roadmap, record its declared base branch, child issues, and planned dev/issue-- integration branch. For a child issue, link the parent roadmap and use its integration branch as the PR base. + - type: textarea id: done attributes: label: Definition of done description: List the acceptance criteria. placeholder: | - - CI green + - make test-all passes on the final local head + - current-head remote CI passes when the PR base is main - benchmark attached - docs updated validations: diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 5af2af13a..837460a65 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -7,12 +7,14 @@ ## Linked Work - Issue: +- Parent roadmap (when applicable): +- Roadmap declared base (when applicable): - Milestone: +- Base branch: ## Validation -- [ ] `make check` -- [ ] `uv run pytest -m "not slow"` +- [ ] `make test-all` passed on the final local head before this PR was created or updated - [ ] Additional task-specific validation listed below Commands actually run: @@ -21,6 +23,11 @@ Commands actually run: # paste exact commands here ``` +Remote CI route: + +- Base `main`: record the current-head CI link and status here. +- Any other base: write `not scheduled; local make test-all is the test gate`. + ## Impact - Backend impact: `mujoco` / `motrix` / both / none diff --git a/AGENTS.md b/AGENTS.md index 4dd206c14..8b02a7549 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -14,13 +14,14 @@ UniLab 是一个 **高性能、模块化、contract 驱动** 的 RL infrastructu 6. **Validate near risk**: 在最接近风险的边界补验证,不只跑顶层命令。 7. **Cold-path asset access only**: asset/XML/model metadata 只允许在 init / materialization / cache 等低频路径处理;热路径不能解析 asset,也不能靠 `getattr` / `hasattr` 探测 backend 私有能力。 -## Roadmap 与 Issue Scope +## Roadmap、Issue 与分支工作流 -- Roadmap 先用普通中文说明:只做什么、不做什么、预计规模和永久维护成本;maintainer 看不懂时必须停止并重写。 -- 一个 implementation issue 只允许一个主要结果,默认不超过 15 个文件、800 行净手写改动和一个 PR;超过即作为 umbrella 拆分,不能整单执行。 -- 批准 roadmap、umbrella 或“新建 issue”只授权规划;“开始开发”默认只授权当前明确确认的第一个 child issue。 -- 新公共 contract、execution path、runner/lifecycle、常规 CI、support 升级或 adapter production 化都必须单独确认,不得顺手扩张。 -- AI review、测试和 gate 不能代替产品判断,也不能证明 maintainer 已理解。 +- Roadmap 先用普通中文说明目标、交付边界、预计规模和永久维护成本,让 maintainer 能够据此作出产品与架构判断。 +- Implementation issue 围绕一个可审查的主要结果组织,并把实现该结果所需的代码、配置、测试和文档作为完整纵向切片。文件数和 LOC 用于估算 review 工作量;是否拆分取决于子项能否独立交付、验证、审查或回退。 +- Roadmap 获得开发授权后,先记录 declared base branch,再从该 base 的最新 head 创建 `dev/issue--` 集成分支;declared base 可以是 `main`,也可以是上层 roadmap 的集成分支。每个 child issue 从本 roadmap 集成分支创建符合仓库类型惯例的分支并通过 PR 合回,最终由集成分支通过 PR 合回 declared base。 +- 已获批的 roadmap 范围支持连续推进 child issues。实施中新增公共 contract、execution path、runner/lifecycle、常规 CI、support 等级或 adapter production 化等长期责任时,先更新边界并请 maintainer 确认。 +- AI review、测试和 gate 为 maintainer 提供决策证据;产品方向与长期维护责任由 maintainer 确认。 +- 每个 PR 在创建或更新前于最终 head 运行 `make test-all`。base 为 `main` 的 PR 使用本地 gate、review 和远程 CI;其他 base 的 PR 使用本地 gate 与 review,远程资源集中用于实际进入 `main` 的合入边界。 详细规则见[协作工作流](docs/sphinx/source/zh_CN/4-developer_guide/5-contributing_workflow.md#ai-roadmap-与-issue-scope-治理)。 @@ -70,7 +71,7 @@ gh api repos///issues/ --jq '.body' ### PR 创建与管理 ```bash -gh pr create --title "标题" --body "内容" --base main +gh pr create --title "标题" --body "内容" --base gh pr list gh pr view ``` @@ -80,10 +81,10 @@ gh pr view 创建或更新 PR 前必须满足: 1. 最终提交已经完成,且 `git status --short --branch` 确认工作树干净。 -2. 最终提交已经通过 `make test-all`。 -3. 如果用户明确说明已经跑过 `make test-all`,不要重复跑;但必须在 PR body 的 Validation 里记录 `make test-all` 已完成。 -4. 如果 `make test-all` 未通过且用户没有明确 override,不要创建或更新 PR。 -5. 创建或更新 PR 后,必须按当前 head SHA 等待远程 CI 全部结束并通过后才能报告完成;`pending` / `in_progress`、旧 head 的成功结果或挂起 job 都不算通过。失败或挂起时必须查看对应 job 日志并修复,除非用户明确 override。 +2. 最终提交已经通过本地 `make test-all`,并在 PR body 的 Validation 中记录结果。用户明确说明已在同一最终 head 运行该命令时,直接采用其结果。 +3. 本地 gate 通过后创建或更新 PR;maintainer 明确批准的 override 需记录在 PR body 中。 +4. PR base 为 `main` 时,按当前 head SHA 等待所有适用的远程 CI 结束并通过后再报告完成。`pending` / `in_progress`、旧 head 的结果和挂起 job 继续跟进;失败时查看对应 job 日志并处理,maintainer 明确批准的 override 除外。 +5. PR base 为集成分支或其他非 `main` 分支时,本地 `make test-all` 结果与 review 共同构成完整合入 gate;远程 CI 在后续实际 base 为 `main` 的 PR 上执行。 ### CI 工作流查看 ```bash @@ -97,7 +98,7 @@ gh run list --status=failure ```bash gh api repos/unilabsim/UniLab/issues/174 --jq '.title, .body' git push -u origin fix/issue-174-ppo-config-alignment -gh pr create --title "fix: xxx" --body "Fixes #174" --base main +gh pr create --title "fix: xxx" --body "Fixes #174" --base ``` ## Context diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4897e2d8a..a8917990b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -25,7 +25,7 @@ Languages: English | [简体中文](docs/sphinx/source/zh_CN/4-developer_guide/4 ## Read Before You Start - Before changing training entrypoints, runners, env contracts, or backend paths, read [RL Infrastructure Development Standard](docs/sphinx/source/zh_CN/4-developer_guide/0-index.md) -- Before changing collaboration flow or issue / milestone rules, read [Collaboration Workflow](docs/sphinx/source/zh_CN/4-developer_guide/5-contributing_workflow.md) +- Before changing collaboration flow or issue / milestone rules, read [Collaboration Workflow](docs/sphinx/source/en/4-developer_guide/5-contributing_workflow.md) ## Common Commands @@ -37,7 +37,7 @@ make check # format + type (required before code-related commits) make test # non-slow tests make test-cov # non-slow tests + coverage report make test-slow # slow integration and training smoke tests -make test-all # make check && make test-cov +make test-all # make check + make test-cov + benchmark entrypoint smoke ``` ## Commit Conventions @@ -54,14 +54,27 @@ Use Conventional Commits: ## Pull Request Workflow -1. For code or config changes, run `make check` locally so lint, mypy, and pyright pass. -2. For code changes, run `make test` locally so non-slow tests pass. -3. If you touched IPC, Runner, or Config, add or update the matching tests. -4. For docs-only changes, run `uv run pytest tests/scripts/test_check_docs.py -q` at minimum. -5. If you touched repository hygiene rules, run `uv run pytest tests/scripts/test_repo_hygiene.py -q`. -6. Link the relevant GitHub issue and fill in validation plus impact scope in the PR template. -7. Open the PR against `main` and wait for green CI. -8. Wait for code review. +1. Choose and record the PR base before development. A roadmap child branches from its current integration branch; other work branches from its intended target branch. +2. Run the tests nearest the changed contract. IPC, Runner, Config, docs, and repository-hygiene changes include their matching focused tests. +3. Run `make test-all` on the final local head before creating or updating every PR, then record the command and result in the PR template. +4. Link the driving issue and describe validation plus impact scope in the PR template. +5. Open the PR against its intended base and complete code review. +6. A PR whose base is `main` completes the applicable remote CI for its current head. A PR to another base uses the recorded local `make test-all` result as its complete test gate; remote execution occurs when an integrated result later reaches a `main`-base PR. + +## Roadmap Integration Workflow + +Once a roadmap issue is approved for development, record its declared base +branch and create `dev/issue--` from that base's latest +head. The declared base may be `main` or another roadmap's integration branch. +Create each child-issue branch from the latest integration branch using the +repository's conventional type prefix, such as +`feat/issue--` or `fix/issue--`, and set the child +PR base to the integration branch. After the approved child issues are +integrated, open the roadmap's final PR back to its declared base. Remote CI is +required when that actual PR base is `main`. + +The detailed scope, authorization, and branch-update rules live in +[Collaboration Workflow](docs/sphinx/source/en/4-developer_guide/5-contributing_workflow.md). ## Issue Reports @@ -70,6 +83,6 @@ Use GitHub Issues to report bugs or propose features. ## Deep References - **Architecture & contracts**: [RL Infrastructure Development Standard](docs/sphinx/source/zh_CN/4-developer_guide/0-index.md) -- **Collaboration & ADR governance**: [Collaboration Workflow](docs/sphinx/source/zh_CN/4-developer_guide/5-contributing_workflow.md) +- **Collaboration & ADR governance**: [Collaboration Workflow](docs/sphinx/source/en/4-developer_guide/5-contributing_workflow.md) - **Test layout & markers**: [Development Standard §Testing](docs/sphinx/source/zh_CN/4-developer_guide/0-index.md) - **Configuration system**: [Development Standard §Configuration](docs/sphinx/source/zh_CN/4-developer_guide/0-index.md) diff --git a/docs/sphinx/source/en/4-developer_guide/1-architecture/1-overview.md b/docs/sphinx/source/en/4-developer_guide/1-architecture/1-overview.md index aae343498..987f67999 100644 --- a/docs/sphinx/source/en/4-developer_guide/1-architecture/1-overview.md +++ b/docs/sphinx/source/en/4-developer_guide/1-architecture/1-overview.md @@ -63,8 +63,8 @@ validation at the boundary a change actually touched. | Backend path | the matching backend smoke run, plus a slow test when needed | | Training entrypoint | the relevant tests plus a 1-iteration smoke run | -Use `make test` for the fast path and `make test-all` (`make check` plus -`make test-cov`) before opening a PR. +Use `make test` for the fast path and `make test-all` (`make check`, +`make test-cov`, and `make test-benchmark-smoke`) before opening a PR. ## Review Checklist diff --git a/docs/sphinx/source/en/4-developer_guide/4-contributing.md b/docs/sphinx/source/en/4-developer_guide/4-contributing.md index a33af7b21..0ec7c79ad 100644 --- a/docs/sphinx/source/en/4-developer_guide/4-contributing.md +++ b/docs/sphinx/source/en/4-developer_guide/4-contributing.md @@ -71,7 +71,8 @@ make test-slow make test-all ``` -For docs-only changes, run: +For documentation changes, run these focused checks in addition to +`make test-all`: ```bash uv run pytest tests/scripts/test_check_docs.py -q @@ -79,9 +80,10 @@ cd docs/sphinx UNILAB_DOCS_SKIP_AUTODOC=1 uv run --no-project --with-requirements requirements.txt sphinx-build -b html -n source build/html ``` -The `Docs` GitHub Actions workflow runs the same prose-only build on matching -PRs and pushes, and it can also be started from the GitHub Actions web UI via -`workflow_dispatch`. It does not install UniLab with `pip install -e .`, does +The `Docs` GitHub Actions workflow runs the same prose-only build for matching +PRs whose base is `main` and for pushes to `main`. It can also be started from +the GitHub Actions web UI via `workflow_dispatch`. It does not install UniLab +with `pip install -e .`, does not generate API reference pages, and does not publish the external docs repository. @@ -100,8 +102,13 @@ uv run --no-sync sphinx-build -j auto -b html -n source build/html - Use Conventional Commits such as `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, and `chore:`. +- Use `main` as the base for an ordinary PR. Use the roadmap's + `dev/issue--` integration branch as the base for a child + PR. See {doc}`5-contributing_workflow` for the complete convention. - Link the driving issue in the PR. - List the validation commands actually run. +- Pass `make test-all` on the final local head before creating or updating every + PR. - State whether behavior differs between MuJoCo, Motrix, macOS, or Linux. - For code/config changes, run the nearest tests for the changed contract before relying on top-level smoke commands. @@ -154,10 +161,23 @@ Notes for `make test-slow`: ## CI Workflow -Pull requests to `main` run five jobs in `.github/workflows/ci.yml`: -`ruff-lint`, `ruff-format`, `mypy`, `pyright`, and `test`. Each is a required -check, and the workflow can also be triggered manually via `workflow_dispatch`. -In-progress runs on the same branch are cancelled automatically. +Remote CI is routed by the PR base: + +| PR base | Local gate | Remote gate | +| --- | --- | --- | +| `main` | `make test-all` passes on the final local head | All applicable checks for the current PR head complete successfully | +| Any other branch, including a roadmap integration branch | `make test-all` passes on the final local head | The local result is the complete test gate; a later PR whose actual base is `main` provides remote execution | + +A child PR can therefore merge into its integration branch after local +validation and review. A roadmap's final PR returns to its declared base: a +`main` base runs remote integration, while another base continues with the local +gate. Record the actual local commands and results in every PR, and add the +current-head remote status when the base is `main`. + +Pull requests to `main` run six jobs in `.github/workflows/ci.yml`: +`ruff-lint`, `ruff-format`, `mypy`, `pyright`, `benchmark-smoke`, and `test`. +They can also be triggered with `workflow_dispatch` for mainline-boundary +diagnostics. In-progress runs on the same branch are cancelled automatically. | Job | What it runs | | --- | --- | @@ -165,7 +185,8 @@ In-progress runs on the same branch are cancelled automatically. | `ruff-format` | `uv run --no-sync ruff format --check .` | | `mypy` | `uv run mypy src/unilab` | | `pyright` | `uv run pyright` | -| `test` | `uv sync --extra motrix` (CPU torch), then `uv run --no-sync pytest -m "not slow" --cov=unilab --cov-fail-under=25` | +| `benchmark-smoke` | `uv run --no-sync python scripts/benchmark/smoke_test.py` in a CPU torch environment | +| `test` | `uv sync --extra mujoco --extra motrix` (CPU torch), then `uv run --no-sync pytest -m "not slow" --cov=src/unilab --cov-fail-under=25` | The `test` job enforces a coverage gate (`--cov-fail-under=25`); the floor only ratchets up as test guardrails improve. Documentation changes are validated by diff --git a/docs/sphinx/source/en/4-developer_guide/5-contributing_workflow.md b/docs/sphinx/source/en/4-developer_guide/5-contributing_workflow.md index c3960e227..9b2b49839 100644 --- a/docs/sphinx/source/en/4-developer_guide/5-contributing_workflow.md +++ b/docs/sphinx/source/en/4-developer_guide/5-contributing_workflow.md @@ -22,6 +22,207 @@ Recommended issue types: - `bug` - `work item`: feature / infra / benchmark / test / sim / docs work +## AI Roadmap, Issue, And Branch Governance + +This section carries forward the focus of [discussion +#883](https://github.com/unilabsim/UniLab/discussions/883) on project direction, +informed decisions, and durable maintenance ownership. It organizes multi-PR +delivery around clear decisions, useful issue boundaries, an integration +branch, and base-aware CI routing. It applies to roadmaps, architecture +issues, and multi-PR plans proposed by AI agents. + +### Communication Baseline + +- UniLab maintainers own product direction and long-term maintenance choices, + using concrete code, configuration, data-flow, and performance evidence. +- The roadmap author translates the proposal into existing repository concepts. + Describe what changes in the repository before introducing an abstraction. +- Introduce each new concept with the problem it solves, the existing modules it + affects, its durable responsibilities, and one repository example. +- AI review, tests, benchmarks, and gates provide implementation evidence. The + owner summary and explicit maintainer choices record product judgment. +- When more context is needed, restate the proposal with shorter language, + concrete paths, and real choices until the delivery boundary is shared. + +### Value And Minimum Complete Design + +A roadmap first answers these questions directly: + +1. Which UniLab core goal does this work serve? +2. Which current code, configuration, tests, bugs, or benchmarks establish the + opportunity? +3. What is the smallest complete design, and how much can reuse the current + owner layer or upstream capability? +4. What are the expected benefit, opportunity cost, and priority basis? +5. Which contracts, execution paths, configurations, tests, CI, or support + responsibilities remain after merge? + +While evidence is still developing, frame the work as research, a benchmark, +or an adapter case study and record the conditions for a later +production/support decision. Each support level then stays aligned with +repository evidence. + +### Roadmap Content + +Organize a roadmap in two layers: + +1. **Owner summary**: a brief plain-language summary, roughly 150 words, + covering the goal, recommended design, delivery boundary, estimated scale, + durable maintenance, and maintainer decisions. +2. **Technical detail**: after direction is confirmed, describe owner + boundaries, data flow, dependencies, risk, validation, child issues, and + integration order. Types, method names, state machines, and performance plans + map to confirmed delivery needs. + +The owner summary should let a maintainer restate: + +> What this roadmap delivers, where its boundary lies, and what the repository +> will maintain afterward. + +Use these writing principles: + +- Put the recommended design before background, terminology, and architecture + detail. +- When a choice is needed, provide two or three real options and state user + value, implementation scale, and long-term cost for each. +- Pair each new abstraction with a repository example and the tradeoff of using + the current structure. +- Specify near-term child issues as executable, verifiable outcomes. Record + farther work as direction, dependencies, and start conditions that evolve + with evidence. +- Record one integrated outcome, the declared base branch, child-issue list, + dependency order, and final acceptance. Add the integration branch after + development authorization. + +### Let Delivery Boundaries Set Issue Size + +Issue size serves understanding, review, and delivery efficiency: + +| Type | Primary purpose | Delivery path | +| --- | --- | --- | +| Roadmap | Define an integrated result, key decisions, and acceptance boundary that require multiple PRs | Collect child PRs on an integration branch, then merge it back to the roadmap's declared base | +| Implementation | Deliver one observable, reviewable result with the code, config, tests, and docs that complete it | Usually one focused PR | +| Research / Benchmark | Produce reproducible evidence and a clear decision result | Independently reviewable artifacts that inform later implementation | + +An implementation issue is a complete vertical slice. Keep these together: + +- the contract, owner implementation, configuration, tests, and user docs for + one behavior; +- adjacent owner-layer changes required to preserve an end-to-end runnable path; +- migration steps whose acceptance value appears only when combined; +- benchmarks, compatibility work, and cleanup required to accept the primary + outcome. + +Create a child issue when a component has one of these properties: + +- it independently produces user or repository value with its own acceptance; +- it has a separate architecture choice, risk decision, review owner, or + delivery cadence; +- it can be reverted independently and collaborates through a stable interface; +- parallel delivery materially shortens the cycle and has clear dependencies. + +File count, handwritten LOC, directory count, owner-layer count, and PR count +are planning signals for review effort and scheduling. Define issue boundaries +by independent delivery value. When an estimate changes materially, update the +issue's scale, dependencies, and review plan, then choose the most coherent +delivery boundary. A helper, one config, a test group, or supporting docs +normally stay with the primary outcome they serve. + +### Writing An Implementation Issue + +Keep the issue body concise, concrete, and directly executable. Longer research +notes, interface drafts, and benchmark data can live in an ADR, document, or +attachment. Include as applicable: + +1. **Problem and evidence**: the opportunity or gap and its repository facts. +2. **Primary deliverable**: the complete capability available after merge. +3. **Delivery boundary**: work included here and related independently delivered + work. +4. **Owner and contract impact**: primary owner layer, adjacent boundaries, and + durable responsibilities. +5. **Roadmap relationship and target branch**: parent roadmap, roadmap declared + base, dependencies, and PR base. +6. **Scale and review plan**: estimated files, handwritten LOC, PR organization, + and appropriate reviewers. +7. **Acceptance and validation**: observable results, focused tests, and required + benchmarks. +8. **Scope-review points**: discoveries that call for an updated design or a + maintainer choice. + +Present product choices explicitly in the owner summary and make technical +detail serve the confirmed boundary. Durable CI, evidence, and support +facilities correspond to reusable long-term needs. Record future ideas with +their start conditions. AI review conclusions follow the maintainer decision as +supporting evidence. + +### Roadmap Integration Branch Workflow + +After explicit roadmap development authorization: + +1. Record the declared base branch in the roadmap issue. It may be `main` or a + parent roadmap's integration branch. Create and push + `dev/issue--` from that base's latest head, following + the repository's existing `dev/issue-*` convention. +2. Create each child-issue branch from the latest integration branch. Use a + change-type prefix such as `feat/issue--`, + `fix/issue--`, `refactor/issue--`, + `perf/issue--`, `test/issue--`, or + `docs/issue--`. +3. Align the child branch's final review head with the current integration + branch, run focused tests plus local `make test-all`, and record the commands + and results in the PR. +4. Set the child PR base to this roadmap's integration branch. Merge after the + local gate and review pass. These PRs use local validation; remote execution + belongs to a PR whose actual base is `main`. +5. Continue through approved child issues in dependency order, honoring product + checkpoints recorded by the roadmap. +6. After all child issues are integrated, run `make test-all` again on the + integration branch's latest head and open the final PR from + `dev/issue-...` back to the declared base. +7. Route the final PR by its actual base: a `main` base waits for current-head + remote CI; another base uses the local gate and review, with remote validation + provided by the later PR that reaches `main`. After merge, clean up this + roadmap's integration and child branches according to normal repository + maintenance practice. + +When the declared base advances during roadmap development, synchronize it at +planned integration points and rerun the local gate on the updated head. +Parallel child issues synchronize the current integration branch before review +so that local results cover the actual merge candidate. + +### Authorization And Scope Review + +Authorization has two explicit stages: + +- **Planning authorization** covers drafting the roadmap, creating issues, + researching evidence, and organizing child issues while repository + implementation stays unchanged. +- **Development authorization** covers one ordinary implementation issue, or + continuous delivery of a roadmap's confirmed boundary and child-issue set + through its integration branch. + +Treat public contracts, execution paths, runner/env lifecycles, training paths, +synchronization protocols, routine CI, support levels, durable +benchmark/evidence facilities, history rewrites, and promotion of an adapter to +a production subsystem as explicit roadmap decisions. Development authorization +covers decisions already confirmed in the owner summary. When implementation +introduces another such decision, update the owner summary, impact, and durable +cost for maintainer confirmation. + +Review the scope when: + +- actual scale, dependencies, or durable responsibilities change materially + from the issue estimate; +- backend work reaches env, manager, runner, or learner contracts outside the + confirmed boundary; +- test results identify a need for a new abstraction or durable facility; +- upstream reuse or a smaller design now satisfies the primary result; +- the maintainer needs a more concrete path, call chain, or tradeoff description. + +A scope review presents current facts, a recommendation, and impacts so the +maintainer can continue, adjust, split, or conclude the work. Record that choice +in the roadmap or implementation issue and continue from the updated boundary. + ## Milestone Structure Each milestone should: @@ -33,7 +234,8 @@ Each milestone should: Typical completion artifacts: -- green CI +- Validation for the PR base: local `make test-all`, plus green remote CI when + the actual base is `main` - benchmark results or W&B run link - demo video / ONNX export / checkpoint path - if user-visible behavior changes, accompanying docs updates @@ -43,8 +245,13 @@ Typical completion artifacts: Every PR should: - Link the driving issue +- Record its base branch; a child PR also links its parent roadmap and integration + branch - Describe user-visible changes and training impact -- List the validation commands actually executed +- List the validation commands actually executed and the final local head's + `make test-all` result +- Record current-head remote CI for a `main` base, or the local gate for any + other base - State whether behavior changes between `mujoco`, `motrix`, macOS, or Linux ## Ownership Model diff --git a/docs/sphinx/source/zh_CN/4-developer_guide/1-architecture/1-overview.md b/docs/sphinx/source/zh_CN/4-developer_guide/1-architecture/1-overview.md index 53b631dac..9b1b65420 100644 --- a/docs/sphinx/source/zh_CN/4-developer_guide/1-architecture/1-overview.md +++ b/docs/sphinx/source/zh_CN/4-developer_guide/1-architecture/1-overview.md @@ -58,8 +58,8 @@ off-policy 算法则使用异步 runner、共享缓冲区,以及位于 `src/un | Backend 路径 | 对应 backend 的 smoke run,必要时补 slow test | | 训练入口 | 相关测试加 1 iteration smoke run | -快速路径用 `make test`;提 PR 前用 `make test-all`(`make check` 加 -`make test-cov`)。 +快速路径用 `make test`;提 PR 前用 `make test-all`(`make check`、 +`make test-cov` 与 `make test-benchmark-smoke`)。 ## 评审清单 diff --git a/docs/sphinx/source/zh_CN/4-developer_guide/4-contributing.md b/docs/sphinx/source/zh_CN/4-developer_guide/4-contributing.md index 392fa9058..2cb993168 100644 --- a/docs/sphinx/source/zh_CN/4-developer_guide/4-contributing.md +++ b/docs/sphinx/source/zh_CN/4-developer_guide/4-contributing.md @@ -62,7 +62,7 @@ make test-slow make test-all ``` -对于仅涉及文档的改动,运行: +文档改动在 `make test-all` 之外运行以下针对性验证: ```bash uv run pytest tests/scripts/test_check_docs.py -q @@ -70,8 +70,9 @@ cd docs/sphinx UNILAB_DOCS_SKIP_AUTODOC=1 uv run --no-project --with-requirements requirements.txt sphinx-build -b html -n source build/html ``` -`Docs` GitHub Actions workflow 会在匹配的 PR 和 push 上运行同样的 prose-only -构建,也可以在 GitHub Actions 网页界面通过 `workflow_dispatch` 手动触发。它不会用 +`Docs` GitHub Actions workflow 会在 base 为 `main` 的匹配 PR 和 `main` push 上运行 +同样的 prose-only 构建,也可以在 GitHub Actions 网页界面通过 `workflow_dispatch` +手动触发。它不会用 `pip install -e .` 安装 UniLab,不生成 API reference 页面,也不发布外部文档仓库。 如果要在本地对完整站点(含面向 `UniLab-doc` 发布流程的 API reference 页面)做最终 @@ -88,8 +89,12 @@ uv run --no-sync sphinx-build -j auto -b html -n source build/html - 使用 Conventional Commits,例如 `feat:`、`fix:`、`docs:`、`refactor:`、 `test:` 与 `chore:`。 +- 普通 PR 以 `main` 为 base;roadmap child PR 以对应 + `dev/issue--` 集成分支为 base。完整约定见 + {doc}`5-contributing_workflow`。 - 在 PR 中关联驱动该工作的 issue。 - 列出实际运行过的验证命令。 +- 每个 PR 在创建或更新前于最终本地 head 通过 `make test-all`。 - 说明行为在 MuJoCo、Motrix、macOS 或 Linux 之间是否存在差异。 - 对于代码/配置改动,在依赖顶层 smoke 命令之前,先运行最接近所改动契约的 测试。 @@ -137,9 +142,20 @@ tests/ ## CI 工作流 -指向 `main` 的 PR 会运行 `.github/workflows/ci.yml` 中的五个 job:`ruff-lint`、 -`ruff-format`、`mypy`、`pyright` 与 `test`。每个都是必需检查,也可通过 -`workflow_dispatch` 手动触发。同一分支上进行中的运行会被自动取消。 +远程 CI 以 PR base 为边界: + +| PR base | 本地 gate | 远程 gate | +| --- | --- | --- | +| `main` | 最终本地 head 通过 `make test-all` | 当前 PR head 的所有适用检查完成并通过 | +| 其他分支(包括 roadmap 集成分支) | 最终本地 head 通过 `make test-all` | 本地结果作为完整测试 gate;远程执行由后续实际 base 为 `main` 的 PR 承担 | + +因此 child PR 在本地验证和 review 后即可合入集成分支。Roadmap 的最终 PR 合回它声明的 +base;该 base 为 `main` 时运行远程集成验证,为其他分支时继续采用本地 gate。PR body +记录实际本地命令与结果,base 为 `main` 时再记录当前 head 的远程检查状态。 + +指向 `main` 的 PR 会运行 `.github/workflows/ci.yml` 中的六个 job:`ruff-lint`、 +`ruff-format`、`mypy`、`pyright`、`benchmark-smoke` 与 `test`。这些 job 也可通过 +`workflow_dispatch` 用于主线边界诊断。同一分支上进行中的运行会被自动取消。 | Job | 内容 | | --- | --- | @@ -147,7 +163,8 @@ tests/ | `ruff-format` | `uv run --no-sync ruff format --check .` | | `mypy` | `uv run mypy src/unilab` | | `pyright` | `uv run pyright` | -| `test` | `uv sync --extra motrix`(CPU torch),再 `uv run --no-sync pytest -m "not slow" --cov=unilab --cov-fail-under=25` | +| `benchmark-smoke` | CPU torch 环境中的 `uv run --no-sync python scripts/benchmark/smoke_test.py` | +| `test` | `uv sync --extra mujoco --extra motrix`(CPU torch),再 `uv run --no-sync pytest -m "not slow" --cov=src/unilab --cov-fail-under=25` | `test` job 施加覆盖率门槛(`--cov-fail-under=25`);这个下限只随测试护栏增强而 逐步上调。文档改动由同一套件中的 `tests/scripts/test_check_docs.py` 校验。独立的 diff --git a/docs/sphinx/source/zh_CN/4-developer_guide/5-contributing_workflow.md b/docs/sphinx/source/zh_CN/4-developer_guide/5-contributing_workflow.md index fc6d46dbd..5507b7d8a 100644 --- a/docs/sphinx/source/zh_CN/4-developer_guide/5-contributing_workflow.md +++ b/docs/sphinx/source/zh_CN/4-developer_guide/5-contributing_workflow.md @@ -24,120 +24,159 @@ ## AI Roadmap 与 Issue Scope 治理 -本节约束由 AI agent 提出的 roadmap、architecture issue 和大型实施计划。技术完整性不能替代产品判断;测试、benchmark、review 和 gate 只能证明实现符合目标,不能证明目标值得做。 +本节延续 [discussion #883](https://github.com/unilabsim/UniLab/discussions/883) +对项目方向、知情决策和长期维护责任的关注,并把实施流程整理为清晰决策、合理 +粒度、集成分支和按 base 分流的 CI。它适用于 AI agent 提出的 roadmap、architecture +issue 和多 PR 实施计划,目标是在规范开发的同时保持连续交付效率。 -### Maintainer 能力与沟通基线 +### 可理解的沟通基线 -- UniLab maintainer 是仓库的主要开发者,具备较强的 RL、机器人仿真、Python、性能优化、配置与训练系统实践能力,也最了解 UniLab 的真实目标和历史约束。 -- 不得把 maintainer 不熟悉 agent 自创术语、编译器式抽象、runtime 分层或企业化治理表述,解释为 maintainer “不专业”。如果主要开发者看不懂 roadmap,首先判定为 roadmap 表达失败。 -- 默认使用中文和仓库中的现有名词。首次出现的新概念必须同时说明:它解决什么问题、会落在哪些现有模块、会新增什么长期负担。能用现有术语表达时不得发明 acronym、layer、runtime 或 protocol 名称。 -- Maintainer 擅长根据具体代码、配置、数据流和性能事实做判断。先给具体影响,再给抽象模型;先说明“仓库会发生什么”,再说明“这个模式叫什么”。 -- Agent 必须对 roadmap 的可理解性负责。不得用“已经有多个 AI review”“技术上自洽”或“所有 gate 可通过”代替 maintainer 本人的理解和判断。 +- UniLab maintainer 负责产品方向和长期维护选择,并依据具体代码、配置、数据流与 + 性能事实作出判断。 +- Roadmap 作者负责把方案翻译成仓库已有概念。默认使用中文和仓库现有名词,先说明 + 仓库会发生什么,再补充必要的抽象名称。 +- 新概念首次出现时,同时说明它解决的问题、对应的现有模块和新增的长期责任,并给出 + 一个仓库内实例。 +- AI review、测试、benchmark 与 gate 提供实现证据;owner summary 与 maintainer + 的明确选择记录产品判断。 +- 当 maintainer 需要更多说明时,作者用更短的表述、具体路径和真实选项重新说明,直到 + 双方对交付边界形成一致理解。 -### 先判断是否值得做 +### 价值与最小方案 -提出 roadmap 前,必须先用简短、直接的语言回答: +Roadmap 首先用简短、直接的语言回答: -1. 这项工作直接服务 UniLab 的哪个核心目标? -2. 当前仓库中有什么证据说明问题真实存在? -3. 最小可行方案是什么?为什么不能只修 owner layer 或做一个薄 adapter? -4. 不做的具体代价是什么? -5. 会新增哪些需要长期维护的 contract、execution path、配置、测试或 CI? +1. 这项工作服务 UniLab 的哪个核心目标? +2. 哪些现有代码、配置、测试、bug 或 benchmark 证明当前机会真实存在? +3. 最小且完整的方案是什么,现有 owner layer 或上游能力可以复用到什么程度? +4. 预期收益、机会成本和优先级依据是什么? +5. 合并后会新增哪些 contract、execution path、配置、测试、CI 或 support 责任? -其中任一项答不清,先调研或建议不做,不得直接生成大型 roadmap。Backend 适配案例不得自动升级为 production backend;性能探索不得自动升级为长期 support claim。 +证据仍在形成时,先把工作定义为 research、benchmark 或 adapter case study,并把升级为 +production/support 的条件写成后续决策点。这样每个支持等级都有与之匹配的仓库证据。 -### Roadmap 的写法 +### Roadmap 的内容结构 -Roadmap 必须分成两层,顺序不可颠倒: +Roadmap 按以下两层组织: -1. **Owner summary**:使用普通中文,控制在约 300 字内,包含问题、推荐的最小方案、明确 non-goals、预估规模和需要 maintainer 决定的事项。 -2. **Technical detail**:只在 owner summary 获得方向确认后展开,描述 owner boundary、数据流、风险和验证。详细类型、方法名、状态机或编译计划只能服务已确认的需求,不能用来制造方案已经成立的印象。 +1. **Owner summary**:使用普通中文,约 300 字,包含目标、推荐方案、交付边界、 + 预估规模、永久维护责任和需要 maintainer 决定的事项。 +2. **Technical detail**:在方向确认后展开 owner boundary、数据流、依赖、风险、验证、 + child issue 和集成顺序。类型、方法名、状态机与性能计划都对应已确认的交付需求。 -Owner summary 必须能让 maintainer 明确回答以下一句话: +Owner summary 应让 maintainer 能够清楚复述: -> 这次只做什么,不做什么,完成后仓库会多出什么永久责任。 +> 这次交付什么,范围边界在哪里,完成后仓库会长期维护什么。 -Roadmap 还必须遵守: +Roadmap 的具体写法遵循以下原则: -- 先给推荐方案,不先堆背景、术语和完整架构图。 -- 需要选择时最多给 2–3 个真实选项,逐项写明用户价值、代码规模和长期成本;不能只比较实现优雅度。 -- 每个新 abstraction 都要给一个仓库内的具体例子和一个“不采用它会怎样”的说明。 -- 不提前设计尚未证明需要的 V2 interface、第二套 runtime/lifecycle、通用 compiler、完整 capability matrix 或 issue-specific evidence system。 -- 多阶段 roadmap 只详细规划最近的 1–3 个可执行 issue;更远阶段只记录方向和启动条件,避免把猜测写成承诺。 -- Roadmap 可作为 umbrella 记录方向,但 **umbrella 获批不等于实施获批**,也不授权 agent 自动依次执行所有 phase。 +- 推荐方案位于背景、术语和架构细节之前。 +- 需要选择时提供 2–3 个真实选项,并逐项说明用户价值、代码规模和长期成本。 +- 每个新 abstraction 配一个仓库内实例,同时说明采用现有结构的可行路径与取舍。 +- 近期 child issue 写到可执行和可验收;远期内容记录方向、依赖与启动条件,并随证据更新。 +- Roadmap 记录一个集成结果、declared base branch、child issue 列表、依赖顺序和最终 + 验收方式。开发授权后再记录对应集成分支。 -### 工作规模与 Issue 上限 +### 以交付边界决定 Issue 粒度 -每个 implementation issue 默认必须能由 maintainer 在一次 review 中理解,并由一个聚焦 PR 完成。 +Issue 粒度服务于理解、review 和交付效率: -| 级别 | 默认规模 | 允许的内容 | 授权规则 | -|------|----------|------------|----------| -| Small | 约 1–8 个文件、≤ 400 行净手写改动 | 一个明确行为、一个 owner layer,以及贴近风险的测试/配置 | 可作为普通 issue 实施 | -| Standard | 约 9–15 个文件、≤ 800 行净手写改动 | 一个纵向切片,最多两个紧邻 owner layer,一个 PR | 实施前确认 scope summary | -| Large / Umbrella | 超过 15 个文件或 800 行;跨 2 个以上 owner layer;预计需要多个 PR | 只用于架构决策、拆分和依赖排序 | 不得直接实施,必须拆成 Small/Standard child issues | +| 类型 | 主要用途 | 交付方式 | +|------|----------|----------| +| Roadmap | 定义一个需要多个 PR 共同完成的集成结果、关键决策和验收边界 | 通过集成分支汇总 child PR,最终合回 roadmap declared base | +| Implementation | 交付一个可观察、可审查的主要结果,以及完成该结果所需的代码、配置、测试和文档 | 通常由一个聚焦 PR 完成 | +| Research / Benchmark | 形成可复现证据和明确决策结论 | 产物可独立审查,并为后续 implementation 提供输入 | -以上数字是默认预算,不是鼓励用满的配额。预计或实际改动达到任一上限时必须暂停并重新评估。机械重命名、生成文件或批量配置迁移可以申请例外,但必须与行为变更分开,并单独报告手写代码和生成内容的规模。 +Implementation issue 采用完整纵向切片。以下内容适合保留在同一个 issue 中: -一个 implementation issue 只能有一个主要结果。不得在同一 issue 中同时承担多个独立目标,例如: +- 同一行为所需的 contract、owner 实现、配置、测试和用户文档; +- 为保持端到端可运行而需要同步调整的相邻 owner layer; +- 只有组合完成才具备验收价值的迁移步骤; +- 主结果验收所需的 benchmark、兼容性处理和清理工作。 -- 公共 contract 重构 + 新 backend production 化; -- manager API 设计 + 两个 task 全量迁移 + 性能融合; -- correctness 实现 + 性能优化 + support 等级提升; -- feature 开发 + 永久 CI/benchmark/evidence 基础设施; -- 仓库清理 + 历史重写 + 新架构落地。 +当子项具备以下任一特征时,拆成 child issue 能提升协作效率: -测试、文档和必要配置属于主结果的组成部分,不算第二个目标;可独立交付、可独立回退的能力必须另立 issue。 +- 可以独立产生用户或仓库价值,并有自己的验收标准; +- 具有独立的架构选择、风险确认、review owner 或交付节奏; +- 可以独立回退,且通过稳定接口与其他子项协作; +- 并行开发可以明显缩短周期,同时依赖边界已经清楚。 -### Issue 的写法 - -Implementation issue 正文应保持短而可决策,主体建议不超过约 1,500 个中文字;更长的研究记录、接口草案或 benchmark 数据放入 ADR、文档或独立附件。Issue 必须按以下顺序书写: - -1. **一句话问题**:当前具体哪里不对。 -2. **为什么现在做**:引用现有代码、配置、测试、bug 或 benchmark 事实。 -3. **最小交付结果**:合并后用户或仓库会得到什么。 -4. **In scope**:3–7 条可审查的工作项。 -5. **Non-goals**:明确列出容易顺手扩张但本次不做的内容。 -6. **Owner 与预计改动**:owner layer、预计文件、手写 LOC 和 PR 数量。 -7. **Acceptance criteria**:3–7 条靠现有 contract、局部测试或必要 benchmark 验证的结果。 -8. **Stop conditions**:什么发现会导致暂停、拆 issue 或回到 maintainer 决策。 - -Issue 不得: - -- 用数十个类型名、方法签名或 phase 掩盖尚未确认的产品选择; -- 把 speculative design 写成已经批准的 contract; -- 用 checklist 数量营造完成度; -- 为单个 issue 创建永久 claim inventory、freshness receipt、raw artifact、专属 CI gate 或项目管理框架; -- 把“以后可能独立成 package”“未来可能 production”写成本 issue 的隐含实施内容; -- 将多个 AI reviewer 的同意作为方案正确或 maintainer 已理解的证据。 - -### 确保 Maintainer 真正理解 - -在开始 Standard、Large、公共 contract 或跨层工作前,agent 必须完成一次理解确认: +文件数、手写 LOC、目录数、owner layer 数和 PR 数作为 review 工作量与排期的规划信号。 +Issue 始终按独立交付价值划分;预估发生明显变化时,更新规模、依赖和 review 方案,再 +选择最连贯的交付边界。一个 helper、一份配置、一组测试或一段配套文档通常与其服务的 +主要结果放在一起。 -1. 给出不依赖新术语的 owner summary; -2. 给出一条明确边界:`只做 X;不做 Y/Z`; -3. 用仓库路径或调用链说明改动落点; -4. 报告预估规模和合并后的永久维护项; -5. 让 maintainer 对真实 trade-off 做选择或明确确认该边界。 - -不要问空泛的“是否理解”。应询问会改变方案的具体问题,例如“只做统一 adapter,还是新增独立 execution path?”如果 maintainer 表示看不懂、无法复述目标,或对范围的理解与 roadmap 不一致,立即停止实施并用更短、更具体的语言重写。不得继续调用其他 AI review 来替代解释。 - -“写 roadmap”“新建 issue”或批准 umbrella,只授权规划和记录;不授权建分支、修改代码或执行所有 child issues。“开始开发”默认只授权当前明确确认的第一个 Small/Standard issue。完成一个 child issue 后,agent 不得自动进入下一个。 - -### 强制暂停条件 - -出现下列任一情况,agent 必须停止扩张,报告当前事实,并由 maintainer 重新决定继续、缩减、拆分或删除: - -- 预计或实际规模超过 issue 中声明的文件/LOC/PR 预算; -- 需要新增公共 contract、runner、env lifecycle、training path 或同步协议; -- 一个 backend 的需求开始向 env、manager、runner 或 learner 扩散; -- 需要新增或修改常规 CI、support 等级、长期 benchmark 或 evidence infrastructure; -- 为了通过测试而需要引入 issue 原目标未提及的新 abstraction; -- 原定 adapter/case study 开始演变为 production subsystem; -- 实现过程中发现最小方案已经足够,或上游能力可以直接复用; -- Maintainer 无法清楚说明当前阶段完成后得到什么。 +### Issue 的写法 -暂停不是失败。删除、缩减或拒绝一项技术上可实现但不服务 UniLab 核心目标的工作,是正确结果。 +Implementation issue 正文保持简短、具体并可直接执行。复杂研究记录、接口草案和大段 +benchmark 数据可放入 ADR、文档或附件。正文按需要包含: + +1. **问题与证据**:当前机会或缺口,以及对应仓库事实。 +2. **主要交付结果**:合并后用户或仓库获得的完整能力。 +3. **范围边界**:本 issue 包含的工作,以及关联但独立交付的工作。 +4. **Owner 与 contract 影响**:主要 owner layer、相邻边界和长期责任。 +5. **Roadmap 关系与 target branch**:parent roadmap、roadmap declared base、依赖 + issue 和 PR base。 +6. **规模与 review 计划**:预计文件、手写 LOC、PR 组织方式和适合的 reviewer。 +7. **Acceptance criteria 与 validation**:可观察结果、局部测试和必要 benchmark。 +8. **范围复核点**:哪些新发现需要更新方案或请 maintainer 选择。 + +产品选择使用 owner summary 显式呈现;技术细节服务于已确认的边界;长期 CI、evidence +或 support 设施对应可复用的长期需求;未来设想以启动条件记录。AI review 结论作为参考 +证据附在 maintainer 决策之后。 + +### Roadmap 集成分支工作流 + +Roadmap 获得明确开发授权后,按以下流程推进: + +1. 在 roadmap issue 中记录 declared base branch。它可以是 `main`,也可以是上层 + roadmap 的集成分支;从该 base 的最新 head 创建并推送 + `dev/issue--`。该命名延续仓库现有 `dev/issue-*` 惯例。 +2. 每个 child issue 从最新集成分支创建工作分支。分支前缀表达改动类型,例如 + `feat/issue--`、`fix/issue--`、 + `refactor/issue--`、`perf/issue--`、 + `test/issue--` 或 `docs/issue--`。 +3. Child branch 在最终 review head 与最新集成分支对齐,运行贴近风险的测试和本地 + `make test-all`,并把实际命令与结果写入 PR。 +4. Child PR 的 base 设置为本 roadmap 集成分支。本地 gate 与 review 通过后合入;这类 + PR 使用本地验证结果,远程执行留给实际 base 为 `main` 的 PR。 +5. 已批准 roadmap 范围内的 child issues 可以按依赖顺序连续推进;roadmap 中声明的产品 + checkpoint 仍在对应位置完成确认。 +6. Child issues 全部集成后,在集成分支最新 head 再运行 `make test-all`,随后创建从 + `dev/issue-...` 合回 declared base 的最终 PR。 +7. 最终 PR 按实际 base 选择 gate:base 为 `main` 时等待当前 head 的远程 CI;base 为 + 其他分支时采用本地 gate 与 review,并由后续进入 `main` 的 PR 承担远程验证。合入完成 + 后按仓库维护习惯清理本 roadmap 的集成分支和 child branches。 + +当 declared base 在 roadmap 开发期间前进时,在计划好的集成点同步该 base,并在同步后的 +head 重新执行本地 gate。并行 child issues 在进入 review 前同步当前集成分支,使每个 +本地结果都覆盖实际合入候选。 + +### 授权与范围复核 + +授权分为两个清晰阶段: + +- **规划授权**:编写 roadmap、创建 issue、研究证据和整理 child issue;仓库实现保持在 + 当前状态。 +- **开发授权**:普通 implementation issue 获得该 issue 的实现权限;roadmap issue 获得 + 已确认交付边界和 child issue 集合的连续实现权限,并启用对应集成分支工作流。 + +以下长期责任作为 roadmap 的显式决策项:公共 contract、execution path、runner/env +lifecycle、training path、同步协议、常规 CI、support 等级、长期 benchmark/evidence +设施、历史重写,以及 adapter 向 production subsystem 的升级。开发授权覆盖 owner +summary 中已经确认的决策项;实施期间新增的决策项先更新 owner summary、影响范围与长期 +成本,再由 maintainer 确认。 + +以下情况触发一次范围复核: + +- 实际规模、依赖或永久维护责任相对 issue 预估出现明显变化; +- backend 改动延伸到原范围外的 env、manager、runner 或 learner contract; +- 测试结果表明需要新的 abstraction 或长期基础设施; +- 上游复用或更小方案已经可以满足主要结果; +- maintainer 需要更具体的路径、调用链或 trade-off 说明。 + +范围复核用当前事实、推荐选项和影响说明支持 maintainer 选择继续、调整、拆分或结束该项 +工作。选择记录回 roadmap 或 implementation issue,后续开发从更新后的边界继续。 ## Milestone 结构 @@ -150,7 +189,8 @@ Issue 不得: 典型的完成产物: -- 绿色 CI +- 与 PR base 对应的验证记录:本地 `make test-all`,以及实际 base 为 `main` 时的绿色 + 远程 CI - benchmark 结果或 W&B run 链接 - demo 视频 / ONNX 导出 / checkpoint 路径 - 如果用户可见行为发生变化,需附带文档更新 @@ -160,8 +200,10 @@ Issue 不得: 每个 PR 应当: - 关联驱动该工作的 issue +- 记录 base branch;child PR 同时关联 parent roadmap 与集成分支 - 描述用户可见的改动与训练影响 -- 列出实际执行过的验证命令 +- 列出实际执行过的验证命令,并记录最终本地 head 的 `make test-all` 结果 +- base 为 `main` 时记录当前 head 的远程 CI;其他 base 记录本地 gate - 说明行为在 `mujoco`、`motrix`、macOS 或 Linux 之间是否变化 ## 所有权模型