贡献指南

一句话总结：如何为项目贡献代码和文档。

📍 本章定位

• 服务方案：全部方案
• 学习方式：📖 选学
• 在流程中的作用：为项目贡献代码和文档
• 核心知识点：贡献流程、代码规范、文档规范
• 预计时长：按需查阅
• 完成后能做什么：能够为项目贡献代码和文档

---

一、贡献总览

1.1 贡献类型

1.2 贡献流程

---

二、代码贡献

2.1 Fork 项目

问题：如何为项目贡献代码？

解决方案：Fork 项目到自己的账号。

操作步骤：

1. 访问项目页面

   https://github.com/your-username/your-project

2. 点击 Fork 按钮

   • 点击右上角的 Fork 按钮
   • 选择自己的账号
   • 等待 Fork 完成

3. 克隆到本地

   git clone https://github.com/your-username/your-project.git
   cd your-project

预期结果：

• 项目 Fork 到自己的账号
• 可以在本地修改代码

2.2 创建分支

问题：如何管理代码版本？

解决方案：使用分支管理。

操作步骤：

1. 创建新分支

   git checkout -b feature/my-feature

2. 切换分支

   git checkout feature/my-feature

3. 查看分支

   git branch

分支命名规范：

类型	命名	示例
功能分支	feature/xxx	feature/user-login
修复分支	fix/xxx	fix/login-bug
文档分支	docs/xxx	docs/api-docs
测试分支	test/xxx	test/user-login

2.3 编写代码

问题：如何编写高质量的代码？

解决方案：遵循代码规范。

代码规范：

规范	说明	工具
命名规范	变量、函数、类命名	PEP 8
代码格式	缩进、空格、换行	Black
类型注解	添加类型注解	MyPy
文档字符串	添加文档字符串	Sphinx

代码示例：

# 好的代码
def calculate_price(quantity: int, price: float) -> float:
    """
    Calculate the total price.
    
    Args:
        quantity: The quantity of items.
        price: The price per item.
    
    Returns:
        The total price.
    """
    return quantity * price

# 不好的代码
def calc(q, p):
    return q * p

2.4 运行测试

问题：如何确保代码质量？

解决方案：运行测试。

操作步骤：

1. 运行单元测试

   pytest

2. 运行集成测试

   pytest --integration

3. 运行端到端测试

   pytest --e2e

4. 运行覆盖率测试

   pytest --cov

测试规范：

规范	说明	工具
测试命名	使用描述性名称	pytest
测试独立	测试之间相互独立	pytest
测试可重复	测试结果一致	pytest
测试快速	测试执行快速	pytest

2.5 提交 PR

问题：如何提交代码变更？

解决方案：提交 Pull Request。

操作步骤：

1. 提交代码

   git add .
   git commit -m "feat: add user login feature"

2. 推送到远程

   git push origin feature/my-feature

3. 创建 PR

   • 访问 GitHub 项目页面
   • 点击 "New Pull Request"
   • 填写 PR 描述
   • 提交 PR

PR 描述模板：

## 描述

简要描述本次变更的内容。

## 变更类型

- [ ] 新功能
- [ ] Bug 修复
- [ ] 性能优化
- [ ] 文档更新
- [ ] 其他

## 测试

描述如何测试本次变更。

## 截图

如果适用，添加截图。

## 相关 Issue

关闭 #123

---

三、文档贡献

3.1 文档编写

问题：如何编写高质量的文档？

解决方案：遵循文档规范。

文档规范：

规范	说明	工具
格式规范	使用 Markdown	Markdown
结构规范	使用标题、列表、表格	Markdown
图片规范	使用高清图片	图片编辑工具
链接规范	使用相对链接	Markdown

文档示例：

# 标题

> 一句话总结

## 二级标题

### 三级标题

- 列表项 1
- 列表项 2

| 列1 | 列2 |
|-----|-----|
| 值1 | 值2 |

![图片描述](图片链接)

3.2 文档翻译

问题：如何翻译文档？

解决方案：使用翻译工具。

翻译规范：

规范	说明	工具
术语规范	使用统一术语	术语表
格式规范	保持格式一致	Markdown
链接规范	更新链接	Markdown

翻译示例：

# 英文原文

This is a sample document.

# 中文翻译

这是一个示例文档。

3.3 文档校对

问题：如何校对文档？

解决方案：使用校对工具。

校对规范：

规范	说明	工具
语法检查	检查语法错误	Grammarly
拼写检查	检查拼写错误	拼写检查工具
格式检查	检查格式错误	Markdown

校对示例：

# 错误示例

This is a sample document with erors.

# 正确示例

This is a sample document with errors.

---

四、测试贡献

4.1 单元测试

问题：如何编写单元测试？

解决方案：使用测试框架。

测试示例：

# test_calculator.py
import pytest
from calculator import add, subtract, multiply, divide

def test_add():
    assert add(2, 3) == 5
    assert add(-1, 1) == 0
    assert add(0, 0) == 0

def test_subtract():
    assert subtract(5, 3) == 2
    assert subtract(1, 1) == 0
    assert subtract(0, 0) == 0

测试规范：

规范	说明	工具
测试命名	使用描述性名称	pytest
测试独立	测试之间相互独立	pytest
测试可重复	测试结果一致	pytest
测试快速	测试执行快速	pytest

4.2 集成测试

问题：如何编写集成测试？

解决方案：使用测试框架。

测试示例：

# test_api.py
import requests

def test_get_users():
    response = requests.get('http://localhost:8000/users')
    assert response.status_code == 200
    assert len(response.json()) > 0

def test_create_user():
    data = {'name': 'John', 'email': 'john@example.com'}
    response = requests.post('http://localhost:8000/users', json=data)
    assert response.status_code == 201
    assert response.json()['name'] == 'John'

测试规范：

规范	说明	工具
测试所有端点	测试所有 API 端点	pytest
测试正常情况	测试正常请求	pytest
测试异常情况	测试异常请求	pytest
测试边界条件	测试边界值	pytest

4.3 端到端测试

问题：如何编写端到端测试？

解决方案：使用测试框架。

测试示例：

// test_e2e.js
const { test, expect } = require('@playwright/test');

test('user can login', async ({ page }) => {
  await page.goto('http://localhost:3000/login');
  await page.fill('#email', 'john@example.com');
  await page.fill('#password', 'password123');
  await page.click('#login-button');
  await expect(page).toHaveURL('http://localhost:3000/dashboard');
});

测试规范：

规范	说明	工具
测试关键流程	测试关键用户流程	Playwright
测试正常情况	测试正常操作	Playwright
测试异常情况	测试异常操作	Playwright
测试不同浏览器	测试不同浏览器	Playwight

---

五、其他贡献

5.1 问题反馈

问题：如何反馈问题？

解决方案：使用 Issue。

反馈规范：

规范	说明	工具
标题规范	使用描述性标题	GitHub Issue
描述规范	详细描述问题	GitHub Issue
复现步骤	提供复现步骤	GitHub Issue
截图	提供截图	GitHub Issue

反馈模板：

## 问题描述

简要描述问题。

## 复现步骤

1. 步骤 1
2. 预期结果
3. 实际结果

## 环境信息

- 操作系统：
- 浏览器：
- 版本：

## 截图

如果适用，添加截图。

5.2 功能建议

问题：如何提出功能建议？

解决方案：使用 Issue。

建议规范：

规范	说明	工具
标题规范	使用描述性标题	GitHub Issue
描述规范	详细描述功能	GitHub Issue
使用场景	描述使用场景	GitHub Issue
实现方案	提供实现方案	GitHub Issue

建议模板：

## 功能描述

简要描述功能。

## 使用场景

描述使用场景。

## 实现方案

提供实现方案。

## 其他信息

其他相关信息。

5.3 代码审查

问题：如何进行代码审查？

解决方案：使用 Pull Request。

审查规范：

规范	说明	工具
代码质量	检查代码质量	GitHub PR
测试覆盖	检查测试覆盖	GitHub PR
文档更新	检查文档更新	GitHub PR
性能影响	检查性能影响	GitHub PR

审查清单：

• [ ] 代码质量检查
• [ ] 测试覆盖检查
• [ ] 文档更新检查
• [ ] 性能影响检查
• [ ] 安全影响检查

---

六、最佳实践

6.1 贡献礼仪

问题：如何进行良好的贡献？

解决方案：遵循贡献礼仪。

礼仪规范：

规范	说明	工具
尊重他人	尊重其他贡献者	GitHub
清晰沟通	清晰表达意图	GitHub
及时响应	及时响应反馈	GitHub
感谢他人	感谢其他贡献者	GitHub

6.2 贡献工具

问题：如何使用贡献工具？

解决方案：使用贡献工具。

工具清单：

工具	用途	命令
Git	版本控制	git
GitHub	代码托管	gh
pytest	测试框架	pytest
Black	代码格式化	black

6.3 贡献流程

问题：如何遵循贡献流程？

解决方案：遵循贡献流程。

流程清单：

---

七、核心洞察

核心洞察

贡献是开源项目的生命线。

• 代码贡献：新功能、Bug 修复、性能优化
• 文档贡献：文档编写、文档翻译、文档校对
• 测试贡献：单元测试、集成测试、端到端测试
• 其他贡献：问题反馈、功能建议、代码审查

记住：贡献不仅是代码，还包括文档、测试、反馈等。

---

八、参考与延伸

[1] GitHub 贡献指南（2026）— GitHub 贡献指南

[2] 开源贡献指南（2026）— 开源贡献指南

[3] Git 贡献指南（2026）— Git 贡献指南

---

九、下一步

完成本章后，进入：

• 工具库总览
• API 文档
• AI Skills 完全指南