From fa6f6866d0c6a303ff46fcf2bbae78c0ad585a6d Mon Sep 17 00:00:00 2001
From: ooooo <3164076421@qq.com>
Date: Mon, 7 Sep 2026 23:12:50 +0800
Subject: [PATCH 1/4] docs(contributing): clarify fork and lint workflow
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

# 📝 Documentation

- Explain how to fork Relax, clone the fork, and open a PR against upstream main in CONTRIBUTING.md and both contribution guides.
- Add the pre-commit installation command to development setup.
- Replace the Black, isort, and Flake8 commands in the English and Chinese guides with pre-commit checks.

## Validation

- Pass pre-commit run --all-files --show-diff-on-failure using a temporary python alias to the installed python3.
- Skip multi-node GPU integration tests because this change only updates documentation.
---
 CONTRIBUTING.md                    | 17 ++++++++++++++---
 docs/en/guide/how-to-contribute.md | 25 +++++++++++--------------
 docs/zh/guide/how-to-contribute.md | 25 +++++++++++--------------
 3 files changed, 36 insertions(+), 31 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index b24745f0..b91fe5f3 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -40,9 +40,11 @@ This project follows a standard code of conduct. Please be respectful, inclusive
 
 ## Development Setup
 
+**Fork** [redai-studio/Relax](https://github.com/redai-studio/Relax) to your account, then run the following commands (replace `<your_user_name>` with your GitHub username):
+
 ```bash
-# Clone the repository
-git clone https://github.com/redai-studio/Relax.git
+# Clone your fork
+git clone https://github.com/<your_user_name>/Relax.git
 cd Relax
 
 # Create virtual environment (recommended)
@@ -54,6 +56,9 @@ pip install -r requirements.txt
 
 # Install in development mode
 pip install -e .
+
+# Install pre-commit
+pip install pre-commit
 ```
 
 ## Development Workflow
@@ -89,7 +94,13 @@ pytest tests/
 
 ### 4. Submit a Pull Request
 
-Push your branch and open a PR against `main`. Fill out the PR template completely.
+Push your branch to your fork:
+
+```bash
+git push origin feature/your-feature-name
+```
+
+On GitHub, open a PR from your branch in your fork to `main` in `redai-studio/Relax` and fill out the PR template.
 
 ## Code Style
 
diff --git a/docs/en/guide/how-to-contribute.md b/docs/en/guide/how-to-contribute.md
index 040881b6..dbf35d11 100644
--- a/docs/en/guide/how-to-contribute.md
+++ b/docs/en/guide/how-to-contribute.md
@@ -6,11 +6,11 @@ Thank you for your interest in contributing to Relax! This guide will help you g
 
 ### 1. Set Up Development Environment
 
-Create a virtual environment and install dependencies:
+**Fork** [redai-studio/Relax](https://github.com/redai-studio/Relax) to your account, then run the following commands (replace `<your_user_name>` with your GitHub username):
 
 ```bash
-# Clone the repository
-git clone https://github.com/redai-studio/Relax.git
+# Clone your fork
+git clone https://github.com/<your_user_name>/Relax.git
 cd Relax
 
 # Create virtual environment
@@ -22,6 +22,9 @@ pip install -r requirements.txt
 
 # Install in development mode
 pip install -e .
+
+# Install pre-commit
+pip install pre-commit
 ```
 
 ### 2. Start Ray and Deploy Services
@@ -77,17 +80,11 @@ pytest tests/utils/test_metrics_service.py
 pytest --cov=relax tests/
 ```
 
-### 4. Format Code
+### 4. Format and Lint Code
 
 ```bash
-# Format with black
-black relax/
-
-# Sort imports
-isort relax/
-
-# Run linter
-flake8 relax/
+# Run pre-commit checks (lint + format)
+pre-commit run --all-files
 ```
 
 ### 5. Commit Changes
@@ -117,10 +114,10 @@ Follow [Conventional Commits](https://www.conventionalcommits.org/):
 ```bash
 # Push to your fork
 git push origin feature/your-feature-name
-
-# Create pull request on GitHub
 ```
 
+On GitHub, open a PR from your branch in your fork to `main` in `redai-studio/Relax` and fill out the PR template.
+
 ## Code Style Guidelines
 
 ### Python Style
diff --git a/docs/zh/guide/how-to-contribute.md b/docs/zh/guide/how-to-contribute.md
index dca0c31e..4b632f43 100644
--- a/docs/zh/guide/how-to-contribute.md
+++ b/docs/zh/guide/how-to-contribute.md
@@ -6,11 +6,11 @@
 
 ### 1. 设置开发环境
 
-创建虚拟环境并安装依赖：
+先将 [redai-studio/Relax](https://github.com/redai-studio/Relax) **Fork** 到自己的账号，再执行以下命令（将 `<your_user_name>` 替换为您的 GitHub 用户名）：
 
 ```bash
-# 克隆仓库
-git clone https://github.com/redai-studio/Relax.git
+# 克隆自己的 fork
+git clone https://github.com/<your_user_name>/Relax.git
 cd Relax
 
 # 创建虚拟环境
@@ -22,6 +22,9 @@ pip install -r requirements.txt
 
 # 以开发模式安装
 pip install -e .
+
+# 安装 pre-commit
+pip install pre-commit
 ```
 
 ### 2. 启动 Ray 并部署服务
@@ -77,17 +80,11 @@ pytest tests/utils/test_metrics_service.py
 pytest --cov=relax tests/
 ```
 
-### 4. 格式化代码
+### 4. 格式化与静态检查
 
 ```bash
-# 使用 black 格式化
-black relax/
-
-# 排序导入
-isort relax/
-
-# 运行 linter
-flake8 relax/
+# 运行 pre-commit 检查（lint + 格式化）
+pre-commit run --all-files
 ```
 
 ### 5. 提交更改
@@ -117,10 +114,10 @@ git commit -m "fix: resolve bug in metrics service"
 ```bash
 # 推送到您的 fork
 git push origin feature/your-feature-name
-
-# 在 GitHub 上创建 pull request
 ```
 
+在 GitHub 上，从您 fork 中的开发分支向 `redai-studio/Relax` 的 `main` 分支提交 PR，并填写 PR 模板。
+
 ## 代码风格指南
 
 ### Python 风格

From 00497539f9de289996f8a23ccb5a93916534b092 Mon Sep 17 00:00:00 2001
From: ooooo <3164076421@qq.com>
Date: Wed, 9 Sep 2026 22:26:10 +0800
Subject: [PATCH 2/4] docs(contributing): streamline contribution guides
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

# 📝 Documentation

## Clarify the development workflow

- Organize the English and Chinese guides into five steps from fork setup
  through unit tests, commits, and pull requests.
- Document upstream synchronization and Git hooks with prek or pre-commit.
- Align testing, documentation, and PR guidance across both languages.

## Update the repository entry point

- Replace duplicate setup commands with a workflow overview and guide link.
- Align the PR checklist with relevant tests and automatic Git hooks.

## Validation

- Run pre-commit checks across all files.
- Verify local links, anchors, bilingual structure, and snippet syntax.
---
 CONTRIBUTING.md                    |  80 +++-----------
 docs/en/guide/how-to-contribute.md | 122 +++++++++------------
 docs/zh/guide/how-to-contribute.md | 164 ++++++++++++++++-------------
 3 files changed, 150 insertions(+), 216 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index b91fe5f3..5bbbc4da 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -8,13 +8,13 @@ Thank you for your interest in contributing to Relax! This document provides gui
 
 - [Code of Conduct](#code-of-conduct)
 - [How Can I Contribute?](#how-can-i-contribute)
-- [Development Setup](#development-setup)
-- [Development Workflow](#development-workflow)
+- [Developing](#developing)
 - [Code Style](#code-style)
 - [Commit Conventions](#commit-conventions)
 - [Pull Request Process](#pull-request-process)
 - [Reporting Bugs](#reporting-bugs)
 - [Requesting Features](#requesting-features)
+- [Community](#community)
 - [License](#license)
 
 ## Code of Conduct
@@ -38,69 +38,15 @@ This project follows a standard code of conduct. Please be respectful, inclusive
 - **Examples** — Add new training examples or tutorials
 - **Testing** — Improve test coverage and add integration tests
 
-## Development Setup
+## Developing
 
-**Fork** [redai-studio/Relax](https://github.com/redai-studio/Relax) to your account, then run the following commands (replace `<your_user_name>` with your GitHub username):
+Follow the [development workflow](docs/en/guide/how-to-contribute.md#developing) for step-by-step commands:
 
-```bash
-# Clone your fork
-git clone https://github.com/<your_user_name>/Relax.git
-cd Relax
-
-# Create virtual environment (recommended)
-python -m venv .venv
-source .venv/bin/activate
-
-# Install dependencies
-pip install -r requirements.txt
-
-# Install in development mode
-pip install -e .
-
-# Install pre-commit
-pip install pre-commit
-```
-
-## Development Workflow
-
-### 1. Create a Branch
-
-```bash
-# Feature
-git checkout -b feature/your-feature-name
-
-# Bug fix
-git checkout -b fix/your-bug-fix
-
-# Documentation
-git checkout -b docs/your-doc-change
-```
-
-### 2. Make Changes
-
-- Follow existing code patterns and conventions
-- Add or update tests for your changes
-- Update documentation if applicable (both English and Chinese)
-
-### 3. Validate
-
-```bash
-# Run pre-commit checks (lint + format)
-pre-commit run --all-files
-
-# Run tests
-pytest tests/
-```
-
-### 4. Submit a Pull Request
-
-Push your branch to your fork:
-
-```bash
-git push origin feature/your-feature-name
-```
-
-On GitHub, open a PR from your branch in your fork to `main` in `redai-studio/Relax` and fill out the PR template.
+1. Fork and clone the repository, add `upstream`, and sync your local `main`.
+2. Create a working branch, set up your environment, and install Git hooks with either prek (recommended) or pre-commit.
+3. Make your changes, add or update tests, and run the relevant unit tests. Update both language versions of the documentation when needed.
+4. Review, stage, and commit your changes using [Conventional Commits](#commit-conventions). Git hooks run automatically on commit; review any fixes and stage them again before retrying.
+5. Push your working branch to your fork and open a PR targeting `redai-studio/Relax`'s `main` branch. Fill out the [PR template](.github/PULL_REQUEST_TEMPLATE.md).
 
 ## Code Style
 
@@ -144,11 +90,11 @@ feat(rollout): add streaming data consumption for async mode
 
 ### Before Submitting
 
-- [ ] Code compiles and runs without errors
-- [ ] `pre-commit run --all-files` passes
-- [ ] Tests pass (`pytest tests/`)
+- [ ] Relevant tests pass locally
+- [ ] Git hooks pass and code is formatted
 - [ ] Documentation updated (if applicable)
 - [ ] Commit messages follow Conventional Commits
+- [ ] Branch is up to date with `main`
 
 ### PR Review
 
@@ -160,7 +106,7 @@ feat(rollout): add streaming data consumption for async mode
 ### Tips for a Good PR
 
 - Keep PRs focused and reasonably sized
-- Provide a clear description of **what**, **why**, and **how**
+- Provide a clear description of **what**, **why**, **how**, and **testing**
 - Link related issues (e.g., `Fixes #123`)
 - Add screenshots or logs for UI or behavior changes
 
diff --git a/docs/en/guide/how-to-contribute.md b/docs/en/guide/how-to-contribute.md
index dbf35d11..25448643 100644
--- a/docs/en/guide/how-to-contribute.md
+++ b/docs/en/guide/how-to-contribute.md
@@ -2,104 +2,70 @@
 
 Thank you for your interest in contributing to Relax! This guide will help you get started.
 
-## Getting Started
+## Developing
 
-### 1. Set Up Development Environment
+### 1. Get the Code
 
-**Fork** [redai-studio/Relax](https://github.com/redai-studio/Relax) to your account, then run the following commands (replace `<your_user_name>` with your GitHub username):
+**Fork** [redai-studio/Relax](https://github.com/redai-studio/Relax) on GitHub, then clone your fork locally. Replace `<your_user_name>` with your GitHub username:
 
 ```bash
-# Clone your fork
 git clone https://github.com/<your_user_name>/Relax.git
 cd Relax
+git remote add upstream https://github.com/redai-studio/Relax.git
 
-# Create virtual environment
-python -m venv .venv
-source .venv/bin/activate  # On Windows: .venv\Scripts\activate
-
-# Install dependencies
-pip install -r requirements.txt
-
-# Install in development mode
-pip install -e .
-
-# Install pre-commit
-pip install pre-commit
+# Sync with the main branch of the upstream repository
+git checkout main
+git pull upstream main
 ```
 
-### 2. Start Ray and Deploy Services
-
-```bash
-# Start Ray cluster
-ray start --head
-
-# Deploy all services
-python -m relax.core.controller deploy --config configs/env.yaml
-```
+`origin` points to your fork, and `upstream` points to the Relax repository. For subsequent contributions, switch to your local `main` and pull upstream updates before creating a working branch. Develop on working branches and keep your local `main` for syncing with upstream.
 
-### 3. Run Example Experiment
+### 2. Set Up for Development
 
 ```bash
-# Run basic example
-python relax/entrypoints/train.py
-
-# Run DeepEyes example
-cd examples/deepeyes
-bash run_deepeyes.sh
+git checkout -b feature/your-change
 ```
 
-## Development Workflow
+For code development, follow the [installation guide](./installation.md) to set up your environment. For documentation, see [Documentation Guidelines](#documentation-guidelines) below.
 
-### 1. Create a Branch
+Choose one of the following tools to install Git hooks. We recommend [prek](https://prek.j178.dev/quickstart/), which is also used in CI:
 
 ```bash
-# Create a feature branch
-git checkout -b feature/your-feature-name
-
-# Or a bugfix branch
-git checkout -b fix/your-bug-fix
+pip install prek
+prek install
 ```
 
-### 2. Make Changes
-
-- Write clean, readable code
-- Follow the existing code style
-- Add tests for new features
-- Update documentation as needed
-
-### 3. Run Tests
+Alternatively, use pre-commit. Both tools read the same `.pre-commit-config.yaml`:
 
 ```bash
-# Run all tests
-pytest tests/
+pip install pre-commit
+pre-commit install
+```
 
-# Run specific test file
-pytest tests/utils/test_metrics_service.py
+Once installed, checks run automatically on each `git commit`.
 
-# Run with coverage
-pytest --cov=relax tests/
-```
+### 3. Run Unit Tests
 
-### 4. Format and Lint Code
+After changing the code, add tests for new or fixed behavior and run the unit tests relevant to your changes. For example, after changing `MetricsClient`:
 
 ```bash
-# Run pre-commit checks (lint + format)
-pre-commit run --all-files
+pytest tests/utils/test_metrics_service.py::TestMetricsClient
 ```
 
-### 5. Commit Changes
+### 4. Commit Changes
 
-```bash
-# Stage changes
-git add .
+After completing the relevant validation, review your changes and stage the files you intend to commit. Replace `<changed-files>` with actual paths, separated by spaces:
 
-# Commit with descriptive message
-git commit -m "feat: add new feature"
-# or
-git commit -m "fix: resolve bug in metrics service"
+```bash
+git status
+git diff
+git add <changed-files>
+git commit -m "feat: describe your change"
 ```
 
-Follow [Conventional Commits](https://www.conventionalcommits.org/):
+If a hook modifies files or reports errors, review and fix the changes, then run `git add` and `git commit` again until the checks pass and the commit succeeds.
+
+Follow [Conventional Commits](https://www.conventionalcommits.org/) for commit messages:
 
 - `feat:` - New feature
 - `fix:` - Bug fix
@@ -109,14 +75,15 @@ Follow [Conventional Commits](https://www.conventionalcommits.org/):
 - `test:` - Adding or updating tests
 - `chore:` - Maintenance tasks
 
-### 6. Push and Create Pull Request
+### 5. Open a PR
 
 ```bash
-# Push to your fork
-git push origin feature/your-feature-name
+git push origin feature/your-change
 ```
 
-On GitHub, open a PR from your branch in your fork to `main` in `redai-studio/Relax` and fill out the PR template.
+On GitHub, open a PR from your working branch in your fork to **`main` in `redai-studio/Relax`**, and fill out the [PR template](https://github.com/redai-studio/Relax/blob/main/.github/PULL_REQUEST_TEMPLATE.md). Replace the branch name in the command if you chose a different one.
+
+Address CI results and review feedback on the same branch, then check, commit, and push your changes. The PR updates automatically.
 
 ## Code Style Guidelines
 
@@ -164,7 +131,6 @@ def compute_reward(
 ### Writing Tests
 
 ```python
-import pytest
 from relax.utils.metrics.client import MetricsClient
 
 def test_metrics_client_log_metric():
@@ -178,6 +144,14 @@ def test_metrics_client_log_metric():
     assert client.get_buffered_metrics_count(step=1) == 1
 ```
 
+### Running Tests
+
+Run the tests relevant to your changes first, for example:
+
+```bash
+pytest tests/utils/test_metrics_service.py
+```
+
 ### Test Coverage
 
 - Aim for >80% code coverage
@@ -188,13 +162,15 @@ def test_metrics_client_log_metric():
 
 ### Adding Documentation
 
-1. Add markdown files to `docs/guide/` or `docs/zh/guide/`
-2. Update `.vitepress/config.mts` to add to sidebar
+1. Add markdown files to  `docs/en/guide/` or `docs/zh/guide/`
+2. Update `docs/.vitepress/config.mts` to add to sidebar
 3. Include code examples and diagrams
 4. Provide both English and Chinese versions
 
 ### Building Documentation
 
+Install Node.js, then run the following commands from the repository root:
+
 ```bash
 # Start documentation dev server
 make docs-dev
diff --git a/docs/zh/guide/how-to-contribute.md b/docs/zh/guide/how-to-contribute.md
index 4b632f43..f905a582 100644
--- a/docs/zh/guide/how-to-contribute.md
+++ b/docs/zh/guide/how-to-contribute.md
@@ -1,105 +1,71 @@
 # 如何贡献
 
-感谢您对 Relax 项目的关注！本指南将帮助您开始贡献。
+感谢你对 Relax 项目的关注！本指南将帮助你开始贡献。
 
-## 开始
+## 开发流程
 
-### 1. 设置开发环境
+### 1. 获取代码
 
-先将 [redai-studio/Relax](https://github.com/redai-studio/Relax) **Fork** 到自己的账号，再执行以下命令（将 `<your_user_name>` 替换为您的 GitHub 用户名）：
+在 GitHub 上 **Fork** [redai-studio/Relax](https://github.com/redai-studio/Relax)，再将你的 fork 克隆到本地。将 `<your_user_name>` 替换为你的 GitHub 用户名：
 
 ```bash
-# 克隆自己的 fork
 git clone https://github.com/<your_user_name>/Relax.git
 cd Relax
+git remote add upstream https://github.com/redai-studio/Relax.git
 
-# 创建虚拟环境
-python -m venv .venv
-source .venv/bin/activate  # Windows: .venv\Scripts\activate
-
-# 安装依赖
-pip install -r requirements.txt
-
-# 以开发模式安装
-pip install -e .
-
-# 安装 pre-commit
-pip install pre-commit
+# 同步主仓库的 main 分支
+git checkout main
+git pull upstream main
 ```
 
-### 2. 启动 Ray 并部署服务
-
-```bash
-# 启动 Ray 集群
-ray start --head
-
-# 部署所有服务
-python -m relax.core.controller deploy --config configs/env.yaml
-```
+`origin` 指向你的 fork，`upstream` 指向 Relax 主仓库。后续贡献前，切回本地 `main` 并拉取上游更新，再创建工作分支。请在工作分支上开发，保持本地 `main` 用于同步主线。
 
-### 3. 运行示例实验
+### 2. 准备开发
 
 ```bash
-# 运行基础示例
-python relax/entrypoints/train.py
-
-# 运行 DeepEyes 示例
-cd examples/deepeyes
-bash run_deepeyes.sh
+git checkout -b feature/your-change
 ```
 
-## 开发工作流
+代码开发环境的配置请参考[安装指南](./installation.md)。文档开发请参考下方[文档指南](#文档指南)。
 
-### 1. 创建分支
+安装 Git hooks 时，以下两种工具任选其一。推荐使用 [prek](https://prek.j178.dev/quickstart/)，CI 也使用该工具：
 
 ```bash
-# 创建功能分支
-git checkout -b feature/your-feature-name
-
-# 或创建修复分支
-git checkout -b fix/your-bug-fix
+pip install prek
+prek install
 ```
 
-### 2. 进行更改
-
-- 编写清晰、可读的代码
-- 遵循现有代码风格
-- 为新功能添加测试
-- 根据需要更新文档
-
-### 3. 运行测试
+也可以使用 pre-commit，两者读取同一份 `.pre-commit-config.yaml`：
 
 ```bash
-# 运行所有测试
-pytest tests/
+pip install pre-commit
+pre-commit install
+```
 
-# 运行特定测试文件
-pytest tests/utils/test_metrics_service.py
+安装后，每次 `git commit` 都会自动运行检查。
 
-# 带覆盖率运行
-pytest --cov=relax tests/
-```
+### 3. 执行单元测试
 
-### 4. 格式化与静态检查
+完成代码修改后，为新增或修复的行为补充测试，并运行与改动相关的单元测试。例如，修改 `MetricsClient` 后：
 
 ```bash
-# 运行 pre-commit 检查（lint + 格式化）
-pre-commit run --all-files
+pytest tests/utils/test_metrics_service.py::TestMetricsClient
 ```
 
-### 5. 提交更改
+### 4. 提交更改
 
-```bash
-# 暂存更改
-git add .
+完成相应验证后，先查看改动，再暂存本次准备提交的文件（将 `<changed-files>` 替换为实际路径，多个路径用空格分隔）：
 
-# 使用描述性消息提交
-git commit -m "feat: add new feature"
-# 或
-git commit -m "fix: resolve bug in metrics service"
+```bash
+git status
+git diff
+git add <changed-files>
+git commit -m "feat: describe your change"
 ```
 
-遵循 [Conventional Commits](https://www.conventionalcommits.org/)：
+如果 hook 自动修改了文件或报告错误，请查看并修正改动，再重新 `git add` 和 `git commit`，直到检查通过并提交成功。
+
+提交消息遵循 [Conventional Commits](https://www.conventionalcommits.org/)：
 
 - `feat:` - 新功能
 - `fix:` - Bug 修复
@@ -109,14 +75,15 @@ git commit -m "fix: resolve bug in metrics service"
 - `test:` - 添加或更新测试
 - `chore:` - 维护任务
 
-### 6. 推送并创建 Pull Request
+### 5. 创建 PR
 
 ```bash
-# 推送到您的 fork
-git push origin feature/your-feature-name
+git push origin feature/your-change
 ```
 
-在 GitHub 上，从您 fork 中的开发分支向 `redai-studio/Relax` 的 `main` 分支提交 PR，并填写 PR 模板。
+在 GitHub 上，从你 fork 中的工作分支向 **`redai-studio/Relax` 的 `main` 分支**创建 PR，并填写 [PR 模板](https://github.com/redai-studio/Relax/blob/main/.github/PULL_REQUEST_TEMPLATE.md)。如果使用了其他分支名，请相应替换命令中的名称。
+
+后续根据 CI 结果和审查意见，在同一分支修改、检查、提交并推送，PR 会自动更新。
 
 ## 代码风格指南
 
@@ -152,12 +119,18 @@ def compute_reward(
         raise ValueError(f"未知的奖励类型: {reward_type}")
 ```
 
+### 文档风格
+
+- 使用清晰、简洁的语言
+- 包含代码示例
+- 在有帮助时添加图表
+- 保持文档更新
+
 ## 测试指南
 
 ### 编写测试
 
 ```python
-import pytest
 from relax.utils.metrics.client import MetricsClient
 
 def test_metrics_client_log_metric():
@@ -171,6 +144,14 @@ def test_metrics_client_log_metric():
     assert client.get_buffered_metrics_count(step=1) == 1
 ```
 
+### 运行测试
+
+优先运行与改动相关的测试，例如：
+
+```bash
+pytest tests/utils/test_metrics_service.py
+```
+
 ### 测试覆盖率
 
 - 目标 >80% 代码覆盖率
@@ -181,13 +162,15 @@ def test_metrics_client_log_metric():
 
 ### 添加文档
 
-1. 将 markdown 文件添加到 `docs/guide/` 或 `docs/zh/guide/`
-2. 更新 `.vitepress/config.mts` 以添加到侧边栏
+1. 将 markdown 文件添加到 `docs/en/guide/` 或 `docs/zh/guide/`
+2. 更新 `docs/.vitepress/config.mts` 以添加到侧边栏
 3. 包含代码示例和图表
 4. 提供中英文两个版本
 
 ### 构建文档
 
+请先安装 Node.js，再在仓库根目录执行以下命令：
+
 ```bash
 # 启动文档开发服务器
 make docs-dev
@@ -218,6 +201,26 @@ make docs-preview
 - **How（如何）**：更改如何工作
 - **Testing（测试）**：如何测试更改
 
+示例：
+
+```markdown
+## What
+为 DeepEyes 示例添加自定义奖励函数支持
+
+## Why
+用户需要灵活定义任务的奖励逻辑
+
+## How
+- 添加 `custom_reward.py` 模块
+- 更新配置以支持自定义奖励函数
+- 添加文档和示例
+
+## Testing
+- 添加自定义奖励函数的单元测试
+- 使用 DeepEyes 示例进行测试
+- 验证向后兼容性
+```
+
 ## 审查流程
 
 1. **自动检查**：CI/CD 运行测试和 linter
@@ -241,6 +244,15 @@ make docs-preview
 - 加入我们的微信群
 - 检查现有 issues 和 PRs
 
+### 报告问题
+
+报告 Bug 时：
+
+- 使用清晰、具有描述性的标题
+- 描述复现步骤
+- 包含错误消息和日志
+- 说明运行环境（操作系统、Python 版本等）
+
 ## 贡献领域
 
 ### 代码
@@ -278,8 +290,8 @@ make docs-preview
 
 ## 许可证
 
-通过为 Relax 做出贡献，您同意您的贡献将根据 Apache 2.0 许可证授权。
+通过为 Relax 做出贡献，你同意你的贡献将根据 Apache 2.0 许可证授权。
 
 ## 感谢！
 
-感谢您为 Relax 做出贡献！您的贡献帮助这个项目变得更好。
+感谢你为 Relax 做出贡献！你的贡献帮助这个项目变得更好。

From 2e30a7188a2c088cf42260d5ee789ea575ad260f Mon Sep 17 00:00:00 2001
From: ooooo-create <106524776+ooooo-create@users.noreply.github.com>
Date: Thu, 10 Sep 2026 00:40:18 +0800
Subject: [PATCH 3/4] Update docs/zh/guide/how-to-contribute.md

Co-authored-by: Nyakku Shigure <sigure.qaq@gmail.com>
---
 docs/zh/guide/how-to-contribute.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/zh/guide/how-to-contribute.md b/docs/zh/guide/how-to-contribute.md
index f905a582..cbaa8921 100644
--- a/docs/zh/guide/how-to-contribute.md
+++ b/docs/zh/guide/how-to-contribute.md
@@ -294,4 +294,4 @@ make docs-preview
 
 ## 感谢！
 
-感谢你为 Relax 做出贡献！你的贡献帮助这个项目变得更好。
+你的每一份提交都在让 Relax 框架越来越完善，感谢你为 Relax 做出的贡献！

From 3a22c7d1bbf4bba7f761e4c23c88a5ac5c840ccd Mon Sep 17 00:00:00 2001
From: ooooo <3164076421@qq.com>
Date: Thu, 10 Sep 2026 00:41:01 +0800
Subject: [PATCH 4/4] apply review

---
 CONTRIBUTING.md                    | 10 +++--
 docs/en/guide/how-to-contribute.md | 59 +++++++++++++++++++----------
 docs/zh/guide/how-to-contribute.md | 61 +++++++++++++++++++-----------
 3 files changed, 83 insertions(+), 47 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 5bbbc4da..874a97bf 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -43,10 +43,12 @@ This project follows a standard code of conduct. Please be respectful, inclusive
 Follow the [development workflow](docs/en/guide/how-to-contribute.md#developing) for step-by-step commands:
 
 1. Fork and clone the repository, add `upstream`, and sync your local `main`.
-2. Create a working branch, set up your environment, and install Git hooks with either prek (recommended) or pre-commit.
-3. Make your changes, add or update tests, and run the relevant unit tests. Update both language versions of the documentation when needed.
-4. Review, stage, and commit your changes using [Conventional Commits](#commit-conventions). Git hooks run automatically on commit; review any fixes and stage them again before retrying.
-5. Push your working branch to your fork and open a PR targeting `redai-studio/Relax`'s `main` branch. Fill out the [PR template](.github/PULL_REQUEST_TEMPLATE.md).
+2. Set up the development environment and install Relax in editable mode.
+3. Run the [DeepEyes example](docs/en/examples/deepeyes.md) to verify the training environment.
+4. Create a working branch and install Git hooks with pre-commit.
+5. Make your changes, add or update tests, and run the relevant unit tests. Update both language versions of the documentation when needed.
+6. Review, stage, and commit your changes using [Conventional Commits](#commit-conventions). Git hooks run automatically on commit; review any fixes and stage them again before retrying.
+7. Push your working branch to your fork and open a PR targeting `redai-studio/Relax`'s `main` branch. Fill out the [PR template](.github/PULL_REQUEST_TEMPLATE.md).
 
 ## Code Style
 
diff --git a/docs/en/guide/how-to-contribute.md b/docs/en/guide/how-to-contribute.md
index 25448643..789f846b 100644
--- a/docs/en/guide/how-to-contribute.md
+++ b/docs/en/guide/how-to-contribute.md
@@ -20,22 +20,40 @@ git pull upstream main
 
 `origin` points to your fork, and `upstream` points to the Relax repository. For subsequent contributions, switch to your local `main` and pull upstream updates before creating a working branch. Develop on working branches and keep your local `main` for syncing with upstream.
 
-### 2. Set Up for Development
+### 2. Set Up the Development Environment
+
+See the [installation guide](./installation.md) for environment requirements.
 
 ```bash
-git checkout -b feature/your-change
+# Create a virtual environment
+python -m venv .venv
+source .venv/bin/activate
+
+# Install dependencies
+pip install -r requirements.txt
+
+# Install in development mode
+pip install -e .
 ```
 
-For code development, follow the [installation guide](./installation.md) to set up your environment. For documentation, see [Documentation Guidelines](#documentation-guidelines) below.
+### 3. Run Example Experiment
 
-Choose one of the following tools to install Git hooks. We recommend [prek](https://prek.j178.dev/quickstart/), which is also used in CI:
+```bash
+# Run basic example
+python relax/entrypoints/train.py
+
+# Run DeepEyes example
+cd examples/deepeyes
+bash run_deepeyes.sh
+```
+
+### 4. Start Developing
 
 ```bash
-pip install prek
-prek install
+git checkout -b feature/your-change
 ```
 
-Alternatively, use pre-commit. Both tools read the same `.pre-commit-config.yaml`:
+Install pre-commit and Git hooks:
 
 ```bash
 pip install pre-commit
@@ -44,15 +62,22 @@ pre-commit install
 
 Once installed, checks run automatically on each `git commit`.
 
-### 3. Run Unit Tests
+### 5. Run Unit Tests
 
-After changing the code, add tests for new or fixed behavior and run the unit tests relevant to your changes. For example, after changing `MetricsClient`:
+After changing the code, add tests for new or fixed behavior and choose the test scope appropriate for your changes:
 
 ```bash
-pytest tests/utils/test_metrics_service.py::TestMetricsClient
+# Run all tests
+pytest tests/
+
+# Run a specific test file
+pytest tests/utils/test_metrics_service.py
+
+# Run with coverage
+pytest --cov=relax tests/
 ```
 
-### 4. Commit Changes
+### 6. Commit Changes
 
 After completing the relevant validation, review your changes and stage the files you intend to commit. Replace `<changed-files>` with actual paths, separated by spaces:
 
@@ -75,7 +100,7 @@ Follow [Conventional Commits](https://www.conventionalcommits.org/) for commit m
 - `test:` - Adding or updating tests
 - `chore:` - Maintenance tasks
 
-### 5. Open a PR
+### 7. Open a PR
 
 ```bash
 git push origin feature/your-change
@@ -144,14 +169,6 @@ def test_metrics_client_log_metric():
     assert client.get_buffered_metrics_count(step=1) == 1
 ```
 
-### Running Tests
-
-Run the tests relevant to your changes first, for example:
-
-```bash
-pytest tests/utils/test_metrics_service.py
-```
-
 ### Test Coverage
 
 - Aim for >80% code coverage
@@ -162,7 +179,7 @@ pytest tests/utils/test_metrics_service.py
 
 ### Adding Documentation
 
-1. Add markdown files to  `docs/en/guide/` or `docs/zh/guide/`
+1. Add markdown files to `docs/en/guide/` or `docs/zh/guide/`
 2. Update `docs/.vitepress/config.mts` to add to sidebar
 3. Include code examples and diagrams
 4. Provide both English and Chinese versions
diff --git a/docs/zh/guide/how-to-contribute.md b/docs/zh/guide/how-to-contribute.md
index cbaa8921..3991505c 100644
--- a/docs/zh/guide/how-to-contribute.md
+++ b/docs/zh/guide/how-to-contribute.md
@@ -20,22 +20,40 @@ git pull upstream main
 
 `origin` 指向你的 fork，`upstream` 指向 Relax 主仓库。后续贡献前，切回本地 `main` 并拉取上游更新，再创建工作分支。请在工作分支上开发，保持本地 `main` 用于同步主线。
 
-### 2. 准备开发
+### 2. 设置开发环境
+
+环境要求见[安装指南](./installation.md)。
 
 ```bash
-git checkout -b feature/your-change
+# 创建虚拟环境
+python -m venv .venv
+source .venv/bin/activate
+
+# 安装依赖
+pip install -r requirements.txt
+
+# 以开发模式安装
+pip install -e .
 ```
 
-代码开发环境的配置请参考[安装指南](./installation.md)。文档开发请参考下方[文档指南](#文档指南)。
+### 3. 运行示例实验
 
-安装 Git hooks 时，以下两种工具任选其一。推荐使用 [prek](https://prek.j178.dev/quickstart/)，CI 也使用该工具：
+```bash
+# 运行基础示例
+python relax/entrypoints/train.py
+
+# 运行 DeepEyes 示例
+cd examples/deepeyes
+bash run_deepeyes.sh
+```
+
+### 4. 开始开发
 
 ```bash
-pip install prek
-prek install
+git checkout -b feature/your-change
 ```
 
-也可以使用 pre-commit，两者读取同一份 `.pre-commit-config.yaml`：
+安装 pre-commit 和 Git hooks：
 
 ```bash
 pip install pre-commit
@@ -44,15 +62,22 @@ pre-commit install
 
 安装后，每次 `git commit` 都会自动运行检查。
 
-### 3. 执行单元测试
+### 5. 执行单元测试
 
-完成代码修改后，为新增或修复的行为补充测试，并运行与改动相关的单元测试。例如，修改 `MetricsClient` 后：
+完成代码修改后，为新增或修复的行为补充测试，并根据改动选择测试范围：
 
 ```bash
-pytest tests/utils/test_metrics_service.py::TestMetricsClient
+# 运行所有测试
+pytest tests/
+
+# 运行特定测试文件
+pytest tests/utils/test_metrics_service.py
+
+# 带覆盖率运行
+pytest --cov=relax tests/
 ```
 
-### 4. 提交更改
+### 6. 提交更改
 
 完成相应验证后，先查看改动，再暂存本次准备提交的文件（将 `<changed-files>` 替换为实际路径，多个路径用空格分隔）：
 
@@ -75,7 +100,7 @@ git commit -m "feat: describe your change"
 - `test:` - 添加或更新测试
 - `chore:` - 维护任务
 
-### 5. 创建 PR
+### 7. 创建 PR
 
 ```bash
 git push origin feature/your-change
@@ -144,14 +169,6 @@ def test_metrics_client_log_metric():
     assert client.get_buffered_metrics_count(step=1) == 1
 ```
 
-### 运行测试
-
-优先运行与改动相关的测试，例如：
-
-```bash
-pytest tests/utils/test_metrics_service.py
-```
-
 ### 测试覆盖率
 
 - 目标 >80% 代码覆盖率
@@ -236,7 +253,7 @@ make docs-preview
 - 对他人友善和尊重
 - 欢迎新人
 - 提供建设性反馈
-- 假定善意
+- 心怀善意
 
 ### 寻求帮助
 
@@ -290,7 +307,7 @@ make docs-preview
 
 ## 许可证
 
-通过为 Relax 做出贡献，你同意你的贡献将根据 Apache 2.0 许可证授权。
+你贡献的代码和文档将按 Apache 2.0 开源许可证发布。
 
 ## 感谢！