Skip to content

贡献指南

Jump to bottom
Keldos edited this page Apr 13, 2023 · 15 revisions

感谢您对 川虎Chat 的关注！我们欢迎您为项目作出贡献！这是一份简短的社区贡献指南：如何做出贡献？

如果您具备一定能力，您可以修改本项目的源代码，并提交一个 pull request。下面的章节将会对这一过程展开具体介绍。

  • 如果您对 git 和 GitHub 的工作流程没有那么了解，那么建议您在提交 pull request 前完整阅读以下内容。
  • 如果您是开源社区的活跃用户，那么也建议您能查看我们的 开发规范 和 提交拉取请求 章节。

开始之前

在一切开始前，请您先检查 <您想要解决的问题> 或 <您想要新增的功能> 等是否在某个 issue 或 pull request 或 discussion 提被到过。如果有，可以先阅读我们的反馈，并以此确定您是否该投入开发（当然，您也可以在原始会话下留言）。

如果没人提到过，为了避免我们与您或其他贡献者重复劳动，建议您采用以下任意一种方式声明，以让他人知晓您正着手解决 <您想要解决的问题> 或 您正着手开发 <您想要新增的功能> ：

  • 使用 功能请求 或 报告BUG 模板提交一个 issue，勾选 我愿意协助开发！ 或 我愿意协助解决！ 复选框，并在 issue 中给出更多您的开发思路和信息。（当您还没尝试开发时）
  • 提交一个 draft pull request，除了写明相关 pull request 信息外，建议您也给出您的开发进度，例如还需要进行的工作等。（当您已经进行过更改并产生过 commit 时）

克隆项目

对于开发者，在克隆本项目之前，我们建议您先fork一份到自己的GitHub账号下，方便我们对您的贡献进行审核和合并：

  1. 打开 川虎Chat 的 GitHub页面，点击“Fork”按钮将项目fork到您的账号下。
  2. 将您账户下的fork仓库克隆到本地： 
    git clone https://github.com/<your-username>/ChuanhuChatGPT.git
cd ChuanhuChatGPT

做出贡献

  1. 创建一个新的分支，并将 HEAD 指向该分支：

    git checkout -b <new-branch-name>

    其中<new-branch-name>为新分支的名称。您可以使用语义化的名称，例如：fixUI、addArg等。

  2. 在该分支上进行代码修改和提交：

    具体的开发规范请参照 开发规范 章节。
    当您完成开发工作后，使用以下命令提交您的更改：

    git add <some-file>
git commit -m "<Your commit message>"

  3. 将更改推送到GitHub：

    push之前，您应当再尝试拉取一下本项目的main分支以更新您的分支。
    请最好使用 pull --rebase 命令变基您自己的分支来同步上游仓库的更新，以避免产生过多的merge信息：

    git pull https://github.com/GaiZhenbiao/ChuanhuChatGPT.git main --rebase

    然后push：

    git push

开发规范

事实上，我们没有太多的开发规范……但为了方便我们对代码的审核，建议您尽力做到一定的规范性：

  • 在编写代码前，先大致阅读代码全文，简要理解本项目的代码风格和命名风格，再开始您的工作。
  • 在撰写 commit message 时，提供简洁而有意义的提交消息和说明，以便其他贡献者可以理解您的更改。
  • 提交消息和代码注释允许使用中文。

另外，对于本项目，还有几个需要您特别注意的点：

  • 注意不要把您的API-KEY推送到远程仓库！
    如果您发现您在commit中误提交了API-Key，可以使用 git commit --amend 或 git rebase 来修正您的更改。
  • 不要更改与您的更改无关的位置的任何空行、缩进或代码风格，注意不要让编辑器的格式化工具自动更改。这会使后期排查blame变得困难。
附录：推荐的 commit message 规范

我们的主要开发者 可能并不遵守 这个规范，但是如果您希望遵守开源社区的守则或学到一些原则，这里给出了我们推荐的 commit message 规范（Keldos改写自Semantic Commit Messages）：

feat: 加入在线搜索功能
^--^  ^-----------^
|     |
|     +-> 摘要: 以现在时态（祈使句形式）撰写的 commit 概要，请务必保持简洁。
|
+-------> 类型: chore, feat, fix, refactor, doc, style... 一般在这几种中选用即可。

您在为本项目做提交时可以遵照执行该规范，也可以只部分执行摘要部分。例如，fix: 修正主框架外背景颜色不匹配问题、加入中止回答的功能、Add command file for macOS 这几种 commit message 都是可以被接受的。

  • 注意摘要使用一般现在时态（祈使句形式）。这意味着，“修复了xxx”，“加入了xxx”使用过去时态其实是不够规范的———想想如果执行“revert”会发生什么。
  • “摘要”部分允许使用中文，但是“类型”部分还是保持英文并在 chore, feat, fix, refactor, doc, style 中选用吧。

提交拉取请求

现在，您将能根据 GitHub 的提示，创建并提交一个拉取请求~

在提交 pull request 之前，最好确保：

  1. 在提交拉取请求之前，您已经用我们的主分支中更新您的分支。
    注意，最好在您将提交push到远程仓库之前执行pull，而不是先push再pull。
    但当您已经提交拉取请求后，就请不要再使用主分支更新您的分支，除非产生了较大的冲突。
  2. 您的代码不会破坏项目的现有功能。
  3. 您自己进行过简单的测试，没有引入新的错误——至少您自己本地运行时没有发现错误。

如果您确保代码没有问题，您可以直接向我们的main分支提交一个 pull request！

拉取请求模板

您可以参考这个示例 pull request：#439

如果您愿意，您创建的拉取请求的标题也应当尽量遵守 开发规范 中的 commit message 规范。

我们建议使用拉取请求模板来帮助您创建高质量的拉取请求。（Copilot For Pull Requests还没出现，别急）
建议使用以下模板，当然只是一个建议———作为开发者，您的代码更重要。

附录：pull request 模板 
### 描述

描述您的pull request所做的更改。

另外请附上相关程序运行时的截图（before & after），以直观地展现您的更改达成的效果。

### 相关问题

（如有）请列出与此拉取请求相关的issue。
或者，您可以直接描述您的工作能解决的问题等。

### 补充信息

请提供任何其他信息或说明，有助于其他贡献者理解您的更改。

如果您提交的是 draft pull request，也请在这里写明开发进度。例子：

#### 开发进度

- [x] 已经做好的事情1
- [ ] 还要干的事情1
- [ ] 还要干的事情2

拉取请求的合并

所有 pull request 都需要被项目管理者审核和接受才能合并到主分支中。如果您的拉取请求需要进行更改，请根据反馈信息进行修改，并持续在您的开发分支上提交。同时，我们也可能直接向您的分支进行提交并产生更改，请注意拉取更新。

您的 pull request 一般会被以 squash merge 的方式合并。这意味着，您 pull request 中的所有 commit 会被压缩成一个 commit 进入我们的 main 分支。现在，您可以安全地删除该分支，并切换回 main 重新拉取我们的代码！

特殊的情况请做出说明，我们会额外考虑。

许可证

通过提交拉取请求，您同意将您的贡献授予该项目的许可证下。

关于许可的疑问和说明，我们在 使用许可 页有详尽的解释。

贡献者们

感谢为本项目做过贡献的人~

近30天的贡献情况

这是 川虎Chat 的 wiki 页面~ 查看主页

Clone this wiki locally