docs(contributing): streamline contribution guides by ooooo-create · Pull Request #302 · redai-studio/Relax

ooooo-create · 2026-09-07T15:14:38Z

What

Update CONTRIBUTING.md and the English and Chinese contribution guides with a consistent workflow from fork to PR.

Why

The existing guides split setup and development into overlapping sections and include outdated commands and documentation paths. Contributors need a clear sequence for preparing, validating, and submitting changes.

How

Organize development into five steps: get the code, set up the environment and Git hooks, run relevant unit tests, commit changes, and open a PR.
Document fork/upstream synchronization and the choice of prek or pre-commit, including automatic checks on commit.
Replace duplicate setup commands in CONTRIBUTING.md with a workflow overview linking to the detailed guide.
Align bilingual reference sections, correct documentation paths.

Testing

pre-commit run --all-files passes (run with --show-diff-on-failure).
Tests pass (pytest tests/) — not run: documentation-only changes; multi-node GPU integration tests were not needed.
New tests added (if applicable) — not applicable.
Documentation updated (if applicable).

Type of Change

Bug fix (non-breaking change that fixes an issue)
New feature (non-breaking change that adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)
Documentation update
Refactoring (no functional changes)
Performance improvement
CI/CD or build changes

Screenshots / Logs

Not applicable.

Copilot

🟡 Changes recommended

The docs should complete the pre-commit setup (pre-commit install) and avoid hardcoded branch names in git push examples to prevent copy/paste failures.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR updates the contribution documentation to reflect the repo’s current workflow: contributors should fork before cloning, and use the repo’s pre-commit configuration (instead of the previously documented Black/isort/Flake8 commands).

Changes:

Document the fork → clone → branch → push-to-fork → PR flow across CONTRIBUTING.md and both language guides.
Add pre-commit installation instructions and standardize on pre-commit run --all-files for lint/format checks.
Keep English and Chinese guides aligned on the updated steps.

File summaries

File	Description
`docs/zh/guide/how-to-contribute.md`	Updates Chinese contributing guide with fork-based workflow and pre-commit-based lint/format instructions.
`docs/en/guide/how-to-contribute.md`	Updates English contributing guide with fork-based workflow and pre-commit-based lint/format instructions.
`CONTRIBUTING.md`	Clarifies top-level contributing steps for external contributors (fork workflow + pre-commit).

Review details

Files reviewed: 3/3 changed files
Comments generated: 6
Review effort level: Lite

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

SigureMo · 2026-09-07T15:18:47Z

 ### 1. 设置开发环境

-创建虚拟环境并安装依赖：
+先将 [redai-studio/Relax](https://github.com/redai-studio/Relax) **Fork** 到自己的账号，再执行以下命令（将 `<your_user_name>` 替换为您的 GitHub 用户名）：


Suggested change

先将 [redai-studio/Relax](https://github.com/redai-studio/Relax) **Fork** 到自己的账号，再执行以下命令（将 `<your_user_name>` 替换为您的 GitHub 用户名）：

先将 [redai-studio/Relax](https://github.com/redai-studio/Relax) **Fork** 到自己的账号，再执行以下命令（将 `<your_user_name>` 替换为你的 GitHub 用户名）：

社区一般不需要使用「您」

SigureMo · 2026-09-07T15:20:49Z

 pip install -e .
+
+# 安装 pre-commit
+pip install pre-commit


pre-commit 安装是不是放在 format and lint 那块比较合适？

SigureMo · 2026-09-08T12:41:51Z

@rai-studio-bot 来 review 下

rai-studio-bot

已按请求完成审查，未发现需要阻塞合入的问题。新增文件可能漏过本地检查的流程问题已在行内评论中说明，并附可直接应用的建议。CI 检查均已通过，PR 标题、说明及测试范围与此次文档改动一致。

^{Powered by Nyanpasu with gpt-6-astra medium, please check the suggestions carefully.}

rai-studio-bot · 2026-09-08T12:52:27Z

-# 运行 linter
-flake8 relax/
+# 运行 pre-commit 检查（lint + 格式化）
+pre-commit run --all-files


优先级：P2

请在检查前将新增文件加入 Git 跟踪。这里替换掉的目录扫描命令会检查新建的 Python 文件，而 pre-commit run --all-files 通过 git ls-files 选择文件，不会包含未跟踪文件。指南直到下一步才执行 git add .，因此按顺序新增模块或测试时，本地 lint/格式化会漏检这些文件，提交后 CI 才会发现问题。

可在此提前暂存，保留下一步的 git add . 以收录格式化产生的修改；英文指南同一位置也请同步调整。

Suggested change

pre-commit run --all-files

# 先暂存本次更改，让新增文件也参与检查

git add .

pre-commit run --all-files

# 📝 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.

# 📝 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.

Copilot

🟢 Approval recommended

Only minor documentation nits were found, and the workflow/tooling updates align with the stated PR goals.

Review details

Files reviewed: 3/3 changed files
Comments generated: 1
Review effort level: Lite

rai-studio-bot

已复查新提交。此前新增文件漏检的问题已解决：中英文指南均改为安装 Git hooks 后暂存、提交，并说明自动修正后的重试步骤。未发现新的行级问题或需要阻塞合入的问题。Pre-commit 检查已通过，三个 Python 版本的测试仍在运行。

优先级：P3 非行级：PR 描述。What 仍称将旧命令替换为 pre-commit run --all-files，但最新指南已改为提交时自动检查。建议更新为“统一 fork、同步主线、测试和提交流程，推荐安装 prek Git hooks，并保留 pre-commit 选项”，使说明与最终改动一致。

^{Powered by Nyanpasu with gpt-6-astra medium, please check the suggestions carefully.}

rai-studio-bot

已核对更新后的标题和描述，现已与最终文档改动一致，上次的描述建议已落实。此前新增文件漏检的问题保持已解决；未发现新的问题，无需新增行内评论。四项 CI 检查均已通过，未发现需要阻塞合入的问题。

^{Powered by Nyanpasu with gpt-6-astra medium, please check the suggestions carefully.}

SigureMo · 2026-09-09T15:36:34Z

-cd examples/deepeyes
-bash run_deepeyes.sh
+git checkout -b feature/your-change
 ```


虚拟环境、跑通示例这块还应该保留，这对开发者来说是一个基础的正反馈，确保第一部设置是对的，后面才是开发

SigureMo · 2026-09-09T15:37:04Z

-
-# 或创建修复分支
-git checkout -b fix/your-bug-fix
+pip install prek


这里不需要提及 prek，继续用 pre-commit 即可

SigureMo · 2026-09-09T15:39:04Z

-# 运行所有测试
-pytest tests/
-
-# 运行特定测试文件
-pytest tests/utils/test_metrics_service.py
-
-# 带覆盖率运行
-pytest --cov=relax tests/


这几种方式我觉得也还是得保留的

SigureMo · 2026-09-09T15:40:59Z

 ## 许可证

-通过为 Relax 做出贡献，您同意您的贡献将根据 Apache 2.0 许可证授权。
+通过为 Relax 做出贡献，你同意你的贡献将根据 Apache 2.0 许可证授权。


这这这，是人话吗？像是英文直译

应该是「你需要遵守 Apache 2.0 开源许可证」之类的？

改成了 “你贡献的代码和文档将按 Apache 2.0 开源许可证发布。”

Co-authored-by: Nyakku Shigure <sigure.qaq@gmail.com>

Copilot

🟢 Approval recommended

Changes are documentation-only and the updated workflow is consistent and aligns with current repo paths and CI hook tooling.

Review details

Suppressed comments (1)

docs/en/guide/how-to-contribute.md:165

There is an extra space before the docs/en/guide/ inline-code path, which renders oddly and can trip markdown linting/format checks.

    # Log metric

Files reviewed: 3/3 changed files
Comments generated: 0 new
Review effort level: Lite

rai-studio-bot

已复查恢复示例和测试命令后的流程。此前新增文件漏检的问题保持已解决；示例运行后的目录衔接问题已在行内评论中说明并附修正建议，暂无需要阻塞合入的问题。Pre-commit 检查已通过，三个 Python 版本的测试仍在运行。

优先级：P3 非行级：PR 描述。最新文档已改为七步且只介绍 pre-commit，How 仍描述五步及 prek/pre-commit 二选一。请将对应两项更新为“按获取代码、设置环境、运行示例、开始开发、单元测试、提交、创建 PR 七步组织流程；使用 pre-commit 安装 Git hooks，在提交时自动检查”，使说明跟上本次调整。

^{Powered by Nyanpasu with gpt-6-astra medium, please check the suggestions carefully.}

rai-studio-bot · 2026-09-09T16:44:06Z

 ```bash
-# 创建功能分支
-git checkout -b feature/your-feature-name
+git checkout -b feature/your-change


优先级：P2

开始开发前请回到仓库根目录。上一节恢复了 cd examples/deepeyes，而 bash run_deepeyes.sh 内的目录切换不会改变调用它的 shell；按顺序执行后，读者仍在示例目录。接下来三条 pytest tests/... 命令都会因该目录下没有 tests/ 而失败，提交步骤中的仓库相对路径也会解析错误。

可在创建分支前显式返回根目录；英文指南对应位置也请同步调整。

Suggested change

git checkout -b feature/your-change

cd "$(git rev-parse --show-toplevel)"

git checkout -b feature/your-change

Copilot

🟡 Changes recommended

The updated guides omit the documented “prek vs pre-commit” choice and drop Windows venv activation guidance, leaving the contribution workflow inconsistent with the PR description and less complete for cross-platform contributors.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Review details

Files reviewed: 3/3 changed files
Comments generated: 5
Review effort level: Lite

+1. Fork and clone the repository, add `upstream`, and sync your local `main`.
+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.


+# Create a virtual environment
 python -m venv .venv
-source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+source .venv/bin/activate


+Install pre-commit and Git hooks:
+
+```bash
+pip install pre-commit
+pre-commit install


 # 创建虚拟环境
 python -m venv .venv
-source .venv/bin/activate  # Windows: .venv\Scripts\activate
+source .venv/bin/activate


+安装 pre-commit 和 Git hooks：
+
+```bash
+pip install pre-commit
+pre-commit install


ooooo-create · 2026-09-09T17:03:49Z

改的有点多了，我再看看

Copilot AI lite review requested due to automatic review settings September 7, 2026 15:14

ooooo-create requested review from NINGBENZHE, Yangruipis and yxyOo as code owners September 7, 2026 15:14

Copilot started reviewing on behalf of ooooo-create September 7, 2026 15:15 View session

Copilot AI reviewed Sep 7, 2026

View reviewed changes

SigureMo reviewed Sep 7, 2026

View reviewed changes

rai-studio-bot reviewed Sep 8, 2026

View reviewed changes

ooooo-create added 2 commits September 9, 2026 21:28

Copilot AI review requested due to automatic review settings September 9, 2026 14:27

ooooo-create force-pushed the docs/contributing-workflow branch from 8ff09e0 to 0049753 Compare September 9, 2026 14:27

Copilot started reviewing on behalf of ooooo-create September 9, 2026 14:28 View session

Copilot AI reviewed Sep 9, 2026

View reviewed changes

Comment thread docs/en/guide/how-to-contribute.md Outdated

rai-studio-bot reviewed Sep 9, 2026

View reviewed changes

ooooo-create changed the title ~~docs(contributing): clarify fork and lint workflow~~ docs(contributing): streamline contribution guides Sep 9, 2026

rai-studio-bot approved these changes Sep 9, 2026

View reviewed changes

SigureMo reviewed Sep 9, 2026

View reviewed changes

Update docs/zh/guide/how-to-contribute.md

2e30a71

Co-authored-by: Nyakku Shigure <sigure.qaq@gmail.com>

Copilot AI review requested due to automatic review settings September 9, 2026 16:40

Copilot started reviewing on behalf of ooooo-create September 9, 2026 16:40 View session

apply review

3a22c7d

Copilot AI reviewed Sep 9, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings September 9, 2026 16:42

Copilot started reviewing on behalf of ooooo-create September 9, 2026 16:43 View session

rai-studio-bot reviewed Sep 9, 2026

View reviewed changes

Copilot AI reviewed Sep 9, 2026

View reviewed changes

	先将 [redai-studio/Relax](https://github.com/redai-studio/Relax) Fork 到自己的账号，再执行以下命令（将 `<your_user_name>` 替换为您的 GitHub 用户名）：
	先将 [redai-studio/Relax](https://github.com/redai-studio/Relax) Fork 到自己的账号，再执行以下命令（将 `<your_user_name>` 替换为你的 GitHub 用户名）：

	git checkout -b feature/your-change
	cd "$(git rev-parse --show-toplevel)"
	git checkout -b feature/your-change

Uh oh!

Conversation

ooooo-create commented Sep 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

Why

How

Testing

Type of Change

Screenshots / Logs

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

SigureMo commented Sep 8, 2026

Uh oh!

rai-studio-bot left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟢 Approval recommended

Uh oh!

Uh oh!

rai-studio-bot left a comment

Choose a reason for hiding this comment

Uh oh!

rai-studio-bot left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟢 Approval recommended

Suppressed comments (1)

Uh oh!

rai-studio-bot left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🟡 Changes recommended

Uh oh!

ooooo-create commented Sep 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

ooooo-create commented Sep 7, 2026 •

edited

Loading