OpenCompass/docs/zh_cn/notes/contribution_guide.md

为 OpenCompass 做贡献

• 为 OpenCompass 做贡献
  • 什么是拉取请求？
  • 基本的工作流：
  • 具体步骤
    • 1. 获取最新的代码库
    • 2. 从 main 分支创建一个新的开发分支
    • 3. 提交你的修改
    • 4. 推送你的修改到复刻的代码库，并创建一个拉取请求
    • 5. 讨论并评审你的代码
    • 6. 拉取请求合并之后删除该分支
  • 代码风格
    • Python

感谢你对于OpenCompass的贡献！我们欢迎各种形式的贡献，包括但不限于以下几点。

• 修改错别字或修复bug
• 添加文档或将文档翻译成其它语言
• 添加新功能和组件

什么是拉取请求？

拉取请求 (Pull Request), GitHub 官方文档定义如下。

拉取请求是一种通知机制。你修改了他人的代码，将你的修改通知原来作者，希望他合并你的修改。

基本的工作流：

1. 获取最新的代码库
2. 从最新的 main 分支创建分支进行开发
3. 提交修改 (不要忘记使用 pre-commit hooks!)
4. 推送你的修改并创建一个 拉取请求
5. 讨论、审核代码
6. 将开发分支合并到 main 分支

具体步骤

1. 获取最新的代码库

• 当你第一次提 PR 时

  复刻 OpenCompass 原代码库，点击 GitHub 页面右上角的 Fork 按钮即可

  克隆复刻的代码库到本地

  git clone git@github.com:XXX/opencompass.git
  

  添加原代码库为上游代码库

  git remote add upstream git@github.com:InternLM/opencompass.git
  

• 从第二个 PR 起

  检出本地代码库的主分支，然后从最新的原代码库的主分支拉取更新。

  git checkout main
  git pull upstream main
  

2. 从 main 分支创建一个新的开发分支

git checkout main -b branchname

3. 提交你的修改

• 如果你是第一次尝试贡献，请在 OpenCompass 的目录下安装并初始化 pre-commit hooks。

  pip install -U pre-commit
  pre-commit install
  

  对于中国地区的用户，由于网络原因，安装 pre-commit hook 可能会失败。可以尝试以下命令切换为国内镜像源：
  ```bash
  pre-commit install -c .pre-commit-config-zh-cn.yaml
  pre-commit run –all-files -c .pre-commit-config-zh-cn.yaml
  ```
  

• 提交修改。在每次提交前，pre-commit hooks 都会被触发并规范化你的代码格式。

  # coding
  git add [files]
  git commit -m 'messages'
  

  有时你的文件可能会在提交时被 pre-commit hooks 自动修改。这时请重新添加并提交修改后的文件。
  

4. 推送你的修改到复刻的代码库，并创建一个拉取请求

• 推送当前分支到远端复刻的代码库

  git push origin branchname
  

• 创建一个拉取请求

  

• 修改拉取请求信息模板，描述修改原因和修改内容。还可以在 PR 描述中，手动关联到相关的议题 (issue),（更多细节，请参考官方文档）。

• 你同样可以把 PR 关联给相关人员进行评审。

5. 讨论并评审你的代码

• 根据评审人员的意见修改代码，并推送修改

6. 拉取请求合并之后删除该分支

• 在 PR 合并之后，你就可以删除该分支了。

  git branch -d branchname # 删除本地分支
  git push origin --delete branchname # 删除远程分支
  

代码风格

Python

我们采用PEP8作为首选的代码风格。

我们使用以下工具进行linting和格式化：

• flake8: 一个围绕一些linter工具的封装器。
• isort: 一个用于排序Python导入的实用程序。
• yapf: 一个Python文件的格式化器。
• codespell: 一个Python实用程序，用于修复文本文件中常见的拼写错误。
• mdformat: mdformat是一个有明确定义的Markdown格式化程序，可以用来在Markdown文件中强制执行一致的样式。
• docformatter: 一个格式化docstring的工具。

yapf和isort的样式配置可以在setup.cfg中找到。