153 lines
3.7 KiB
Markdown
153 lines
3.7 KiB
Markdown
# 开源贡献指南
|
||
|
||
感谢你愿意为本项目贡献代码、文档或想法。本文介绍从领取 Issue 到提交 Pull Request（PR）的完整流程。
|
||
|
||
## 贡献方式
|
||
|
||
你可以通过以下方式参与项目：
|
||
|
||
- 报告 Bug 或补充复现信息
|
||
- 提出功能建议
|
||
- 改进代码、测试和性能
|
||
- 完善文档、示例或翻译
|
||
- 参与 Issue 讨论和代码审查
|
||
|
||
## 1. 选择或创建 Issue
|
||
|
||
开始工作前，请先查看现有 Issue，确认没有其他人正在处理相同问题。
|
||
|
||
如果没有对应 Issue，可以新建一个，并写清楚：
|
||
|
||
- 问题背景或使用场景
|
||
- 期望结果
|
||
- 建议的实现范围
|
||
- 可验证的验收标准
|
||
|
||
领取任务后，在 Issue 中说明你准备处理，并等待维护者确认范围。
|
||
|
||
## 2. 获取仓库
|
||
|
||
```bash
|
||
git clone https://www.gitlink.org.cn/yuting2003/cc.git
|
||
cd cc
|
||
```
|
||
|
||
开始修改前同步默认分支：
|
||
|
||
```bash
|
||
git checkout master
|
||
git pull origin master
|
||
```
|
||
|
||
## 3. 创建贡献分支
|
||
|
||
每项工作都应使用独立分支，避免直接修改 `master`：
|
||
|
||
```bash
|
||
git checkout -b docs/open-source-contribution-guide
|
||
```
|
||
|
||
推荐的分支命名方式：
|
||
|
||
- `feature/<名称>`：新增功能
|
||
- `fix/<名称>`：修复问题
|
||
- `docs/<名称>`：文档修改
|
||
- `test/<名称>`：测试相关修改
|
||
- `refactor/<名称>`：代码重构
|
||
|
||
分支名称应简短、明确，并使用小写英文和连字符。
|
||
|
||
## 4. 完成修改并自检
|
||
|
||
修改时请尽量保持每个 PR 只解决一个问题。提交前建议检查：
|
||
|
||
```bash
|
||
git status
|
||
git diff
|
||
```
|
||
|
||
如果项目提供测试、格式化或构建命令，请在提交前执行并记录结果。文档修改需要检查标题层级、链接、代码块和错别字。
|
||
|
||
不要提交以下内容：
|
||
|
||
- 密码、Token、私钥或其他凭据
|
||
- 本地配置和包含个人信息的文件
|
||
- 与当前 Issue 无关的大量格式化变更
|
||
- 构建产物、缓存或临时文件
|
||
|
||
## 5. 创建 Commit
|
||
|
||
将相关文件加入暂存区：
|
||
|
||
```bash
|
||
git add docs/open-source-contribution-guide.md
|
||
git commit -m "docs: 添加开源贡献指南"
|
||
```
|
||
|
||
推荐使用清晰的提交类型：
|
||
|
||
- `feat`：新功能
|
||
- `fix`：问题修复
|
||
- `docs`：文档修改
|
||
- `test`：测试修改
|
||
- `refactor`：代码重构
|
||
- `chore`：工具或维护工作
|
||
|
||
一个 Commit 应表达一个完整、可理解的修改意图。
|
||
|
||
## 6. 推送分支
|
||
|
||
```bash
|
||
git push -u origin docs/open-source-contribution-guide
|
||
```
|
||
|
||
首次推送使用 `-u` 建立跟踪关系，后续更新可直接运行 `git push`。
|
||
|
||
## 7. 创建 Pull Request
|
||
|
||
在 GitLink 仓库页面从贡献分支向 `master` 创建 PR，并填写：
|
||
|
||
- 简明的标题
|
||
- 修改背景和主要内容
|
||
- 测试或检查结果
|
||
- 关联的 Issue，例如 `关联 Issue #1`
|
||
|
||
也可以使用 GitLink CLI：
|
||
|
||
```bash
|
||
gitlink-cli pr +create \
|
||
--owner yuting2003 \
|
||
--repo cc \
|
||
--title "docs: 添加开源贡献指南" \
|
||
--head docs/open-source-contribution-guide \
|
||
--base master \
|
||
--body "关联 Issue #1，新增开源贡献流程与提交规范。"
|
||
```
|
||
|
||
## 8. 响应代码审查
|
||
|
||
收到审查意见后，继续在同一分支修改并推送：
|
||
|
||
```bash
|
||
git add .
|
||
git commit -m "docs: 根据审查意见完善贡献指南"
|
||
git push
|
||
```
|
||
|
||
新 Commit 会自动加入原 PR，无需重新创建。
|
||
|
||
讨论解决后再标记对应审查意见为已处理。不要通过强制推送覆盖其他贡献者的工作。
|
||
|
||
## PR 提交前检查清单
|
||
|
||
- [ ] 修改内容与关联 Issue 的范围一致
|
||
- [ ] 分支基于最新的 `master`
|
||
- [ ] 已执行适用的测试、格式化或构建检查
|
||
- [ ] Commit 信息准确描述修改
|
||
- [ ] PR 标题和描述清晰完整
|
||
- [ ] 已关联对应 Issue
|
||
- [ ] 没有提交任何敏感信息
|
||
- [ ] 没有混入无关文件或大范围格式化变更
|
||
|
||
感谢你的贡献！
|