贡献指南

开源的核心就是与他人沟通，也就是解决冲突的过程。该指南的初衷就是为初学者提供一个简单的方法去学习以及参与开源项目。

如何贡献

我们欢迎各种形式的贡献！请根据你的目标选择对应的方式：

  • 🐛 提交 Bug 报告：如果你发现了 Bug，请点击下方链接，直接填写 Bug 报告表单：点击这里提交 Bug 报告
  • 💡 功能建议：请在 Issues 中描述你的想法和使用场景，与我们讨论后再着手开发。
  • 📖 改进文档：可以直接提交 Pull Request 修改文档中的错别字或表述不清之处。
  • 💻 贡献代码：请参考下方的“代码贡献流程”，从 Fork 仓库开始。

如果你的电脑上未安装 git 或对命令行不熟悉，请参考以下的 软件安装。git跟github的使用可以参考以下的视频教程 git github详细使用视频教程链接

在cmd/bash提交本地修改的步骤

flowchart LR A[1. fork 组织项目到个人账户] --> B[2. clone 个人远程仓库到本地] B --> C[3. 新建特性分支] C --> D[4. 进行修改] D --> E[5. add 修改到暂存区] E --> F[6. commit 更改到本地仓库] F --> G[7. push 分支到远程仓库] G --> H[8. 创建 Pull Request] H --> I{评审通过?} I -->|是| J[合并到主分支] I -->|否| K[根据反馈修改] K --> E style A fill:#e1f5fe style B fill:#e1f5fe style C fill:#ccffcc style D fill:#fff3e0 style E fill:#dff3e0 style F fill:#dff3e0 style G fill:#dff3e0 style I fill:#f3e5f5 style J fill:#f3e5f5 style K fill:#fff3e0

1. 注册 并登陆 Github 账号，在 想要修改的开源孪创仓库 页面右上角点击Fork，然后点击Create a new fork，创建分叉到个人仓库。

2.克隆个人仓库（若出现SSL certificate problems请关闭加速器再克隆）： 

# 注意：该命令中的 {用户名} 替换为自己的用户名，hutb 替换为想要修改的仓库名，否则没有权限直接修改组织仓库
git clone https://github.com/{用户名}/hutb.git

3.新建特性分支

进入刚才克隆的仓库目录。第 2 步以 hutb 为例，这里也进入 hutb：

cd hutb

如果第 2 步克隆的是 .github，则使用 cd .github。目录名要与实际克隆的仓库一致。

接下来使用 git switch 命令新建一个分支。下面以修正文档为例： 

git switch -c docs-fix-contribution-steps

分支名可以按本次修改的内容调整；后面的推送命令使用同一个分支名。

4.修改仓库的文件

打开任意文件，更新文件内容，保存修改。然后使用 git status 列出被改动的文件（后面步骤都可以使用该命令进行状态查看）。

5-7.修改并本地测试没问题后，提交修改到个人仓库（参考 git 命令说明）。先查看差异，确认文件和内容都是本次准备提交的修改：

git status
git diff

下面以修改 README.md 为例。git add 后填写能说明具体改动的提交信息，再推送当前分支：

git add README.md
git diff --cached
git commit -m "docs: 说明 README 中的项目入口 / clarify project links in README"
git push -u origin docs-fix-contribution-steps

将 README.md 换成实际修改的文件，例如修改贡献指南时使用 git add CONTRIBUTING.md；提交信息也要与实际改动对应。如果第 3 步用了其他分支名，推送时同步替换。

如果在 push（推送）过程中出 error（错误），点击这里 - ### Authentication Error 
remote: Support for password authentication was removed on August 13, 2021. Please use a personal access token instead.
  remote: Please see https://github.blog/2020-12-15-token-authentication-requirements-for-git-operations/ for more information.
  fatal: Authentication failed for 'https://github.com//first-contributions.git/'
去 [GitHub 的教程](https://docs.github.com/zh/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account) 学习如何生成新的 SSH 密匙以及配置。

8. 推送后，在个人仓库页面切换到刚才的分支，点击 Contribute 创建 Pull Request。确认目标仓库是原来的 OpenHUTB 仓库，目标分支是该仓库的默认分支，来源是个人仓库中本次修改的分支。比如 OpenHUTB/.github 的默认分支是 master，不要直接填成 main。

填写能概括修改内容的标题和说明后提交，等待审核。如果个人仓库落后于原仓库，先通过 Sync fork 同步，并把最新内容合并到本次修改的分支；有冲突时先解决，再提交。

不久之后，团队成员便会把你所有的变化合并到这个项目的主分支。更改合并后，你会收到一封电子邮件通知。

在VScode提交本地修改的步骤

1.工具准备

  • 首先按上述步骤创建GitHub账号，这里不多赘述；
  • 点击VScode左下角小猫图标登录GitHub账号；
  • 在VScode扩展商店安装“GitHub Pull Requests”扩展，它把git add、git commit、git push和git branch这些命令都变成了点击操作，对新手很友好，强烈建议把Chinese Language Pack for Visual Studio Code这个汉化扩展也装上，安装成功之后重启。

2.克隆个人仓库

  • 该步骤与第一个方法里的一致，不过多赘述。

3.新建并更改分支

  • 这一步相当于新建一个副本，在这个副本上面你可以做任何事，且不会损坏、污染主分支。
  • 在VScode左下角，也就是图一所示位置，会看到master或者main的字样，这意味着你现在在主分支，点击他，上方对话框会出现创建新分支...，点击他就可以创建新分支，成功后如图二所示，创建了一个名为new的分支，并且自动跳转到了这个分支，这时候就可以按需修改了。

图一 图二

4.暂存修改并提交

  • 暂存，也就是 git add 操作，用来选择这次要提交的修改；git commit 会把已经暂存的修改保存为一次提交。只保存文件还不等于完成提交。
  • 如图三所示，点击左边第三个源代码管理图标，在存储库这一栏可以看到新建的分支和主分支，如果下方的更改一栏是空的，说明你现在所处的分支不对，点击对应分支即可切换。随后点击加号即可暂存成功。 确保保存并暂存所有修改后，在提交按钮上方的对话框输入本次的说明，就可以提交了。

图三

5.本地预览

  • 如下图所示，点击第二行第二个放大镜图标就可以直接预览渲染后的网页效果。

图四

6.发布Branch

  • 在提交之后，这些修改已经在本地存档完毕了，只需上传，这时点击发布Branch按钮，最上方对话框会出现2个选择，origin对应你自己的云端仓库，upstream对应你fork的原仓库。

  • 注：请确保发布分支前已经测试过准确无误

7.Pull Requests

  • 发布成功后，回到自己的仓库，会出现一个如图所示提醒，点击绿色按钮。 图五

  • 这时会跳转到新页面，在合并仓库前找到下图所示位置，这表示把你的修改合并到原仓库，但为了确保万无一失，强烈建议更改目标仓库为自己的仓库，在自己仓库测试没有问题再向原仓库提出PR请求。

图六

  • 成功之后，这次向自己仓库发起的PR会显示为open状态，点击Merge pull request，直到其状态变为紫色，这时候再去自己仓库，就会发现修改已经同步上去了。
  • 测试完毕没有问题就可以向原仓库发送PR请求了。

8. 本地检查Pull requests请求

有人发送Pull requests时，可以在 GitHub 上合并之前测试并验证更改 。 

# 拉取Pull Request 的 ID 为 7，并在本地新建分支名为 7 的命令：git fetch origin pull/7/head:7
git fetch origin pull/ID/head:BRANCH_NAME
# 切换到新建的分支
git switch BRANCH_NAME
# 前面拉取后，后面又有新的修改
git pull origin pull/ID/head

在 Pull Request 页面的 File changed 中，对有相关问题或修改建议的代码行进行审核并填写评论内容，并点击 Start a review，所有都评论完成后，点击 Submit review 提交评论，对方就会收到审核意见的邮件。

所有问题解决并且本地验证通过后，点击 Pull Request 页面中最下面的“Squash and merge”（注意不是默认的“Create a merge commit”）。至此，一次的提交最终完成。

注意事项：

  • Pull Request 标题需要概括所修改的内容；
  • 尽量少包含二进制文件；
  • 不提交程序能够输出的中间文件、结果文件；
  • 可以提供少量能够保证程序能够正常运行的示例数据，大的输入数据在 README.md 文件中提供百度网盘或者谷歌网盘的下载链接；

其他

1.如果提交 Pull Request 时出现冲突，则参考 使用 TortoiseGit 解决冲突 或 在 GitHub 上解决合并冲突 。

2.同步子模块 

git submodule update --remote

软件安装

Git Visual Studio 2017 VS Code IntelliJ IDEA
First Contributions流程 Visual Studio 2022简单入门教程 Visual Studio Code下载网址 Pycharm学习教程

问题

国内访问 github 可能较慢

这里提供 github 加速方案和科学上网的 链接 。

向 github 上 push 的时候报 403 错误

打开.git/config，比如： 

url = https://github.com/OpenHUTB/bazaar.git
将你用户名复制粘贴到github前面再加个@，变成： 
url = https://OpenHUTB@github.com/OpenHUTB/bazaar.git
然后就可以进行授权并继续push。
克隆个人仓库出错

若出现SSL certificate problems请关闭加速器再克隆。

git push 报错unexpected disconnect while reading sideband packet
# 增加缓存至4G
git config --global http.postBuffer 4048576000