docs(chore): refresh OSS governance and v0.8.0 user docs

Mr-tooth · Copilot · Mr-tooth · commit 659282326ca5 · 2026-04-17T20:56:59.000+08:00
Co-authored-by: Copilot &lt;223556219+Copilot@users.noreply.github.com&gt;
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -1,4 +1,12 @@
 repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: check-merge-conflict
+      - id: check-yaml
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+
   - repo: https://github.com/astral-sh/ruff-pre-commit
     rev: v0.15.9
     hooks:
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -11,13 +11,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 - Added startup font-size controls for GUI entry commands via `--font-size` (`small|medium|large|xlarge`) with environment fallback `RMP_GUI_FONT_SIZE`.
+- Added OSS governance baseline guidance via `CLAUDE.md` and OSS-focused release checks.
 
 ### Changed
 - Refactored GUI font-size handling to track per-size availability and reject unavailable selections with explicit status feedback.
+- Updated OSS quickstart and IK docs to align with v0.8.0 font-size startup behavior.
 
 ### Fixed
 - Fixed persistent runtime font-size issue where only `small` effectively applied when higher-size font handles were unavailable.
 - Hardened font installation to fail per size instead of aborting the full font registry initialization path.
+- Updated OSS docs/release tests to validate OSS-owned artifacts only.
 
 ## [0.7.9] - 2026-04-15
 
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -0,0 +1,33 @@
+# CLAUDE.md
+
+## Scope
+- Applies to the full `robot-motion-player-oss` repository.
+- Instruction precedence: system/developer rules > `AGENTS.md` > this file > default docs.
+
+## Source of Truth (OSS)
+- User onboarding: `README.md`, `docs/QUICKSTART_en.md`, `docs/QUICKSTART_zh.md`
+- IK behavior and workflows: `docs/IK_USAGE.md`
+- Release-facing history: `CHANGELOG.md`
+
+## Standard Workflow
+1. Install development dependencies with `make install-dev`.
+2. Validate changes with:
+   - `make lint`
+   - `make test` (or `make test-quick` while iterating)
+   - `make check` before handoff
+3. For release or docs-governance updates, also run `make release-check`.
+4. Update tests/docs whenever user-facing behavior changes.
+
+## Implementation Guardrails
+- State explicit assumptions when requirements are ambiguous.
+- Prefer the simplest viable solution; avoid speculative abstractions.
+- Keep changes surgical and within task scope.
+- Keep OSS tests scoped to OSS-owned files only.
+
+## Release-Sensitive Rules
+- Keep version markers synchronized by role:
+  - `pyproject.toml`: release version `X.Y.Z`
+  - `motion_player/__init__.py`: metadata fallback `X.Y.Z.dev0`
+  - `motion_player/cli/main.py`: `_get_version` fallback `X.Y.Z.dev0`
+- Keep `CHANGELOG.md`, `docs/QUICKSTART_en.md`, `docs/QUICKSTART_zh.md`, and `docs/IK_USAGE.md` aligned with release behavior.
+- Run `make release-check` before tagging.
diff --git a/Makefile b/Makefile
@@ -3,10 +3,11 @@
 .DEFAULT_GOAL := help
 
 PIP ?= pip
+PYTEST ?= pytest
 
 help: ## Show available development targets
 	@echo "robot-motion-player development commands"
-	@awk 'BEGIN {FS = ":.*##"} /^[a-zA-Z0-9_.-]+:.*##/ {printf "  %-14s %s\n", $$1, $$2}' $(MAKEFILE_LIST)
+	@awk 'BEGIN {FS = ":.*##"} /^[a-zA-Z0-9_.-]+:.*##/ {printf "  %-14s %s\\n", $$1, $$2}' $(MAKEFILE_LIST)
 
 install-dev: ## Install package with development dependencies
 	$(PIP) install -e ".[dev]"
@@ -15,15 +16,15 @@ lint: ## Run Ruff lint checks
 	ruff check motion_player tests
 
 test: ## Run full pytest suite
-	pytest tests/ -v --tb=short
+	$(PYTEST) tests/ -v --tb=short
 
 test-quick: ## Run targeted fast test subset
-	pytest tests/gui/test_dearpygui_panel.py tests/backends/test_mujoco_viewer.py tests/core/test_ui.py -q
+	$(PYTEST) tests/gui/test_dearpygui_panel.py tests/backends/test_mujoco_viewer.py tests/core/test_ui.py -q
 
 check: lint test ## Run lint and tests
 
 precommit: ## Run pre-commit on all files
 	pre-commit run --all-files
 
-release-check: lint test ## Run release checks and verify version markers
-	python scripts/release/check_release_markers.py
+release-check: lint test ## Run OSS release checks
+	$(PYTEST) -q tests/test_docs_version_state.py tests/test_release_backfill_state.py tests/test_roadmap_versions.py
diff --git a/RELEASING.md b/RELEASING.md
@@ -1,39 +1,36 @@
 # RELEASING.md
 
-This guide describes the standard release workflow for `robot-motion-player`.
+This guide describes the standard OSS release workflow for `robot-motion-player`.
 
 ## 1) Pre-release checks
 
-1. Confirm release scope and prepare notes in `docs/releases/vX.Y.Z.md`.
-2. Update `CHANGELOG.md`:
-   - move relevant items from `[Unreleased]` into `## [X.Y.Z] - YYYY-MM-DD`.
+1. Confirm release scope and collect release notes in `CHANGELOG.md`.
+2. Update the `## [Unreleased]` section and promote release entries to `## [X.Y.Z] - YYYY-MM-DD`.
 3. Synchronize version markers by role:
    - `pyproject.toml`: `[project].version = "X.Y.Z"` (release version)
    - `motion_player/__init__.py`: metadata fallback `"X.Y.Z.dev0"`
    - `motion_player/cli/main.py`: `_get_version()` fallback `"X.Y.Z.dev0"`
-4. Run validations:
+4. Keep OSS user docs aligned with the release behavior:
+   - `docs/QUICKSTART_en.md`
+   - `docs/QUICKSTART_zh.md`
+   - `docs/IK_USAGE.md`
+5. Run validations:
    - `make release-check`
    - optional: `make precommit`
 
 ## 2) Tag and publish
 
-1. Commit release changes (version sync, changelog, release notes).
+1. Commit release changes (version sync, changelog, docs).
 2. Create annotated tag:
    - `git tag -a vX.Y.Z -m "Release vX.Y.Z"`
 3. Push branch and tag:
    - `git push origin <branch>`
    - `git push origin vX.Y.Z`
-4. Create GitHub release from `vX.Y.Z` and use `docs/releases/vX.Y.Z.md` as the release body.
-5. For historical release backfill workflows, use:
-   - `bash scripts/release/backfill_releases.sh`
+4. Create GitHub release from `vX.Y.Z` and use the corresponding `CHANGELOG.md` section as the release body.
 
 ## 3) Post-release checks
 
 1. Verify the Git tag and GitHub release point to the intended commit.
 2. Verify version markers from local source files:
-   - `python scripts/release/check_release_markers.py`
-   - optional installed-package sanity check: `motion_player --version`
-3. Ensure release docs are synchronized:
-   - `CHANGELOG.md`
-   - `docs/releases/RELEASE_TAG_MAP.md`
-4. Keep `## [Unreleased]` in `CHANGELOG.md` ready for the next cycle.
+   - `motion_player --version`
+3. Keep `## [Unreleased]` in `CHANGELOG.md` ready for the next cycle.
diff --git a/docs/IK_USAGE.md b/docs/IK_USAGE.md
@@ -20,6 +20,18 @@ Both runtime backend paths (`.xml` MuJoCo and `.urdf` Pinocchio when installed)
 
 Unit conversion is done only at the UI/payload boundary.
 
+## GUI Startup Font Size (v0.8.0)
+
+For GUI entry commands, startup font-size can be set with `--font-size`:
+
+```bash
+motion_player play --motion <clip.pkl> --robot <robot.xml> --gui --font-size large
+motion_player gui --motion <clip.pkl> --robot <robot.xml> --font-size xlarge
+```
+
+Supported values are `small`, `medium`, `large`, `xlarge`.
+You can set `RMP_GUI_FONT_SIZE` as the default startup selection.
+
 ## GUI Workflow
 
 Use either:
diff --git a/docs/QUICKSTART_en.md b/docs/QUICKSTART_en.md
@@ -27,6 +27,23 @@ motion_player gui --motion path/to/clip.pkl --robot path/to/robot.xml
 `motion_player gui` now prefers an isolated panel process mode. If panel startup fails,
 the runtime prints a warning and continues in MuJoCo keyboard-only mode.
 
+### v0.8.0 GUI startup font-size controls
+
+Use startup font-size selection when launching GUI entry commands:
+
+```bash
+motion_player play --motion path/to/clip.pkl --robot path/to/robot.xml --gui --font-size large
+motion_player gui --motion path/to/clip.pkl --robot path/to/robot.xml --font-size xlarge
+```
+
+You can also set a default via environment variable:
+
+```bash
+export RMP_GUI_FONT_SIZE=medium
+```
+
+Supported values: `small`, `medium`, `large`, `xlarge`.
+
 ## 3) Essential keys
 
 - `Space`: play/pause
@@ -55,16 +72,6 @@ if no CJK font is available, the panel falls back to the best readable platform
 The output menu provides a `Clear` action, and export progress advances per rendered frame.
 For details, see [IK Usage Guide](IK_USAGE.md).
 
-GUI visual QA command (desktop session):
-
-```bash
-RMP_GUI_SNAPSHOT_OUT=/tmp/rmp-monitor-card.png \
-RMP_GUI_LAYOUT_REPORT_OUT=/tmp/rmp-monitor-card-layout.json \
-motion_player play --motion path/to/clip.pkl --robot path/to/robot.xml --gui
-```
-
-Expected report field in `/tmp/rmp-monitor-card-layout.json`: `"fits_all_lines": true`.
-
 ## 4) Generate quality report
 
 ```bash
@@ -102,7 +109,7 @@ Notes:
 motion_player export \
   --motion path/to/clip.pkl \
   --robot path/to/robot.xml \
-  --output /tmp/clip.gif \
+  --output clip.gif \
   --fps 20
 ```
 
diff --git a/docs/QUICKSTART_zh.md b/docs/QUICKSTART_zh.md
@@ -27,6 +27,23 @@ motion_player gui --motion path/to/clip.pkl --robot path/to/robot.xml
 `motion_player gui` 现在默认优先使用面板隔离进程模式。
 若面板启动失败，运行时会打印告警并自动回退到 MuJoCo 键盘控制模式。
 
+### v0.8.0 GUI 启动字号控制
+
+可在 GUI 入口命令启动时指定字号：
+
+```bash
+motion_player play --motion path/to/clip.pkl --robot path/to/robot.xml --gui --font-size large
+motion_player gui --motion path/to/clip.pkl --robot path/to/robot.xml --font-size xlarge
+```
+
+也可通过环境变量设置默认值：
+
+```bash
+export RMP_GUI_FONT_SIZE=medium
+```
+
+支持值：`small`、`medium`、`large`、`xlarge`。
+
 ## 3）常用按键
 
 - `Space`：播放/暂停
@@ -54,16 +71,6 @@ Tune 工作流采用双层数据流：`Current Pose`（运行态只读）与 `Ta
 输出菜单提供 `清空` 操作，导出进度条按逐帧渲染进度更新。
 当前 IK 说明请参考 [IK 使用说明](IK_USAGE.md)。
 
-GUI 可视化质检命令（桌面会话）：
-
-```bash
-RMP_GUI_SNAPSHOT_OUT=/tmp/rmp-monitor-card.png \
-RMP_GUI_LAYOUT_REPORT_OUT=/tmp/rmp-monitor-card-layout.json \
-motion_player play --motion path/to/clip.pkl --robot path/to/robot.xml --gui
-```
-
-`/tmp/rmp-monitor-card-layout.json` 的期望字段：`"fits_all_lines": true`。
-
 ## 4）导出质量报告
 
 ```bash
@@ -101,7 +108,7 @@ motion_player convert --input path/to/robot.xml --output path/to/robot.urdf
 motion_player export \
   --motion path/to/clip.pkl \
   --robot path/to/robot.xml \
-  --output /tmp/clip.gif \
+  --output clip.gif \
   --fps 20
 ```
 
diff --git a/tests/test_docs_version_state.py b/tests/test_docs_version_state.py
@@ -1,6 +1,4 @@
-"""Version and roadmap consistency checks."""
-
-from __future__ import annotations
+"""Version and OSS docs consistency checks."""
 
 from pathlib import Path
 
@@ -32,37 +30,26 @@ def test_version_markers_follow_project_version() -> None:
     assert f'return "{expected_dev_version}"' in cli_text
 
 
-def test_design_and_summary_keep_full_gui_roadmap_order() -> None:
-    design = Path("docs/design.md").read_text(encoding="utf-8")
-    summary = Path("docs/summary.md").read_text(encoding="utf-8")
-    assert "**Version / 版本**: 0.7.0" in design
-    assert "| v0.5.0  | Full GUI integration milestone" in design
-    assert "| v0.6.0  | IK tuning workflow hardening" in design
-    assert "| v0.7.0  | Marked-frame history and quick revisit UX in CLI/GUI" in design
-    assert "| v0.8.x  | Font architecture stabilization and reliability hardening" in design
-    assert "| v0.9.x  | Physics replay (PD control), deterministic tests" in design
-    assert "| v1.0.0  | Isaac/NV backend, HDF5 support, plugin completion" in design
-    assert "| v1.1.0  | Web/Jupyter viewer export, packaging/distribution hardening" in design
-    assert "Phase 5 — Full GUI Integration (Milestone 0.5.0)" in summary
-    assert "Phase 6 — IK Tuning Workflow + Conversion Interop (Milestone 0.6.0)" in summary
-    assert "Phase 7 — Marked-Frame UX + Docs/Release Sync (Milestone 0.7.0)" in summary
-    assert (
-        "Phase 8 — Font Architecture Stabilization + Reliability Hardening (Milestone 0.8.x)"
-        in summary
-    )
-    assert "Phase 9 — Physics Replay + Advanced Evaluation (Milestone 0.9.0)" in summary
-    assert "Phase 10 — Multi-Backend & Plugin System (Milestone 1.0.0)" in summary
-    assert "Phase 11 — Distribution & Community (Milestone 1.1.0)" in summary
+def test_v080_docs_align_with_font_size_release_behavior() -> None:
+    quickstart_en = Path("docs/QUICKSTART_en.md").read_text(encoding="utf-8")
+    quickstart_zh = Path("docs/QUICKSTART_zh.md").read_text(encoding="utf-8")
+    ik_usage = Path("docs/IK_USAGE.md").read_text(encoding="utf-8")
+    changelog = Path("CHANGELOG.md").read_text(encoding="utf-8")
+
+    assert "## [0.8.0]" in changelog
+    assert "--font-size" in changelog
+    assert "RMP_GUI_FONT_SIZE" in changelog
 
+    for text in (quickstart_en, quickstart_zh, ik_usage):
+        assert "--font-size" in text
+        assert "RMP_GUI_FONT_SIZE" in text
 
-def test_readme_has_professional_banner_and_dual_mode_sections() -> None:
+
+def test_readme_references_oss_docs_only() -> None:
     readme = Path("README.md").read_text(encoding="utf-8")
-    readme_cn = Path("README_CN.md").read_text(encoding="utf-8")
-    assert "![RMP Banner](docs/assets/banner.svg)" in readme
-    assert "## CLI Mode" in readme
-    assert "## Full GUI Mode" in readme
-    assert "[中文 README](README_CN.md)" in readme
-    assert "[English README](README.md)" in readme_cn
-    assert "https://github.com/YanjieZe/GMR" in readme
-    assert "https://github.com/Mr-tooth/rsl-rl-ex" in readme
-    assert "jGMR" not in readme
+
+    assert "[English](README.md)" in readme
+    assert "[中文](docs/QUICKSTART_zh.md)" in readme
+    assert "docs/QUICKSTART_en.md" in readme
+    assert "docs/IK_USAGE.md" in readme
+    assert "README_CN.md" not in readme
diff --git a/tests/test_release_backfill_state.py b/tests/test_release_backfill_state.py
@@ -1,23 +1,34 @@
-"""Release tag map and backfill-script consistency checks."""
-
-from __future__ import annotations
+"""OSS release governance checks."""
 
 from pathlib import Path
 
+PRIVATE_RELEASE_PATHS = (
+    Path("docs/releases"),
+    Path("scripts/release/backfill_releases.sh"),
+)
+
+
+def test_private_release_artifacts_are_not_present_in_oss() -> None:
+    for path in PRIVATE_RELEASE_PATHS:
+        assert not path.exists(), f"private-only artifact should be absent in OSS: {path}"
+
 
-def test_release_map_covers_v040_to_v052() -> None:
-    text = Path("docs/releases/RELEASE_TAG_MAP.md").read_text(encoding="utf-8")
-    for tag in ("v0.4.0", "v0.4.1", "v0.5.0", "v0.5.1", "v0.5.2"):
-        assert f"| {tag} |" in text
+def test_releasing_guide_targets_oss_artifacts() -> None:
+    text = Path("RELEASING.md").read_text(encoding="utf-8")
 
+    assert "CHANGELOG.md" in text
+    assert "docs/QUICKSTART_en.md" in text
+    assert "docs/QUICKSTART_zh.md" in text
+    assert "docs/IK_USAGE.md" in text
+    assert "docs/releases" not in text
+    assert "backfill_releases.sh" not in text
 
-def test_backfill_script_lists_v040_to_v052() -> None:
-    text = Path("scripts/release/backfill_releases.sh").read_text(encoding="utf-8")
-    for tag in ("v0.4.0", "v0.4.1", "v0.5.0", "v0.5.1", "v0.5.2"):
-        assert tag in text
 
+def test_make_release_check_uses_oss_tests() -> None:
+    text = Path("Makefile").read_text(encoding="utf-8")
 
-def test_release_note_files_exist_for_v040_to_v052() -> None:
-    for tag in ("v0.4.0", "v0.4.1", "v0.5.0", "v0.5.1", "v0.5.2"):
-        path = Path(f"docs/releases/{tag}.md")
-        assert path.exists()
+    assert "release-check" in text
+    assert "tests/test_docs_version_state.py" in text
+    assert "tests/test_release_backfill_state.py" in text
+    assert "tests/test_roadmap_versions.py" in text
+    assert "scripts/release/check_release_markers.py" not in text
diff --git a/tests/test_roadmap_versions.py b/tests/test_roadmap_versions.py
