docs(contributing): clarify fork and lint workflow - #302
Conversation
# 📝 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.
There was a problem hiding this comment.
🟡 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-filesfor 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.
| # Install pre-commit | ||
| pip install pre-commit |
| Push your branch to your fork: | ||
|
|
||
| ```bash | ||
| git push origin feature/your-feature-name |
| # Install pre-commit | ||
| pip install pre-commit |
| # Push to your fork | ||
| git push origin feature/your-feature-name |
| # 安装 pre-commit | ||
| pip install pre-commit |
| # 推送到您的 fork | ||
| git push origin feature/your-feature-name |
| ### 1. 设置开发环境 | ||
|
|
||
| 创建虚拟环境并安装依赖： | ||
| 先将 [redai-studio/Relax](https://github.com/redai-studio/Relax) **Fork** 到自己的账号，再执行以下命令（将 `<your_user_name>` 替换为您的 GitHub 用户名）： |
There was a problem hiding this comment.
| 先将 [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 用户名）： |
社区一般不需要使用「您」
| pip install -e . | ||
|
|
||
| # 安装 pre-commit | ||
| pip install pre-commit |
There was a problem hiding this comment.
pre-commit 安装是不是放在 format and lint 那块比较合适？
|
@rai-studio-bot 来 review 下 |
rai-studio-bot
left a comment
rai-studio-bot
left a comment
There was a problem hiding this comment.
已按请求完成审查，未发现需要阻塞合入的问题。新增文件可能漏过本地检查的流程问题已在行内评论中说明，并附可直接应用的建议。CI 检查均已通过，PR 标题、说明及测试范围与此次文档改动一致。
| # 运行 linter | ||
| flake8 relax/ | ||
| # 运行 pre-commit 检查（lint + 格式化） | ||
| pre-commit run --all-files |
There was a problem hiding this comment.
请在检查前将新增文件加入 Git 跟踪。这里替换掉的目录扫描命令会检查新建的 Python 文件，而 pre-commit run --all-files 通过 git ls-files 选择文件，不会包含未跟踪文件。指南直到下一步才执行 git add .，因此按顺序新增模块或测试时，本地 lint/格式化会漏检这些文件，提交后 CI 才会发现问题。
可在此提前暂存，保留下一步的 git add . 以收录格式化产生的修改；英文指南同一位置也请同步调整。
| pre-commit run --all-files | |
| # 先暂存本次更改，让新增文件也参与检查 | |
| git add . | |
| pre-commit run --all-files |
What
Complete the fork-to-PR workflow in
CONTRIBUTING.mdand the English and Chinese contribution guides. Add pre-commit installation instructions and replace the guides' outdated Black, isort, and Flake8 commands withpre-commit run --all-files.Why
The guides clone the upstream repository directly, leaving external contributors without a writable push destination. The formatting instructions also differ from the repository's current pre-commit configuration.
How
Explain how to fork and clone the repository, push a named branch to the fork, and open a PR against
redai-studio/Relax:main. Keep the English and Chinese instructions aligned.Testing
pre-commit run --all-filespasses (run with--show-diff-on-failure; a temporarypythonalias pointed to the installedpython3).pytest tests/) — not run: documentation-only changes; integration tests require multi-node GPU hardware.Also verified
git diff --checkand matching command examples in the English and Chinese guides.Type of Change
Screenshots / Logs
Not applicable.