14 KiB
14 KiB
贡献指南
感谢您对身体平衡评估系统项目的关注！我们欢迎所有形式的贡献，包括但不限于代码、文档、测试、问题报告和功能建议。
目录
行为准则
我们的承诺
为了营造一个开放和友好的环境，我们作为贡献者和维护者承诺，无论年龄、体型、残疾、种族、性别认同和表达、经验水平、国籍、个人形象、种族、宗教或性取向如何，参与我们项目和社区的每个人都能获得无骚扰的体验。
我们的标准
有助于创造积极环境的行为包括：
- 使用友好和包容的语言
- 尊重不同的观点和经验
- 优雅地接受建设性批评
- 关注对社区最有利的事情
- 对其他社区成员表示同理心
不可接受的行为包括：
- 使用性化的语言或图像，以及不受欢迎的性关注或性骚扰
- 恶意评论、侮辱/贬损评论，以及个人或政治攻击
- 公开或私下骚扰
- 未经明确许可，发布他人的私人信息，如物理或电子地址
- 在专业环境中可能被合理认为不适当的其他行为
如何贡献
贡献类型
我们欢迎以下类型的贡献：
-
代码贡献
- 新功能开发
- Bug 修复
- 性能优化
- 代码重构
-
文档贡献
- API 文档
- 用户指南
- 开发者文档
- 代码注释
-
测试贡献
- 单元测试
- 集成测试
- 端到端测试
- 性能测试
-
设计贡献
- UI/UX 设计
- 图标设计
- 用户体验改进
-
其他贡献
- 问题报告
- 功能建议
- 社区支持
- 翻译工作
开发环境设置
前置要求
- Python 3.8+
- Node.js 16.0+
- Git
- 代码编辑器（推荐 VS Code）
环境配置
-
克隆仓库
git clone https://github.com/example/body-balance-evaluation.git cd body-balance-evaluation -
安装依赖
# Windows install.bat # 或手动安装 python -m venv venv venv\Scripts\activate # Windows # source venv/bin/activate # macOS/Linux pip install -r backend/requirements.txt cd src/renderer && npm install -
配置开发环境
# 复制配置文件 cp config.json config.local.json # 编辑本地配置（可选） # 修改 config.local.json 中的设置 -
启动开发服务器
# Windows start_dev.bat # 或手动启动 python main.py --mode development
开发工具推荐
VS Code 扩展
- Python
- Pylance
- Vue Language Features (Volar)
- TypeScript Vue Plugin (Volar)
- ESLint
- Prettier
- GitLens
浏览器扩展
- Vue.js devtools
- React Developer Tools（如果使用）
代码规范
Python 代码规范
我们遵循 PEP 8 规范：
# 好的示例
class PatientManager:
"""患者管理器类"""
def __init__(self, database_path: str):
self.db_path = database_path
self.logger = logging.getLogger(__name__)
def create_patient(self, patient_data: dict) -> int:
"""创建新患者
Args:
patient_data: 患者信息字典
Returns:
患者ID
Raises:
ValueError: 当患者数据无效时
"""
if not self._validate_patient_data(patient_data):
raise ValueError("Invalid patient data")
# 实现逻辑...
return patient_id
代码格式化
使用 Black 进行代码格式化：
black . --line-length=88
代码检查
使用 flake8 进行代码检查：
flake8 . --max-line-length=88 --exclude=venv,__pycache__
JavaScript/Vue 代码规范
我们遵循 Vue.js 风格指南：
// 好的示例
export default {
name: 'PatientList',
props: {
patients: {
type: Array,
required: true
},
loading: {
type: Boolean,
default: false
}
},
emits: ['patient-selected', 'patient-deleted'],
setup(props, { emit }) {
const selectedPatient = ref(null)
const handlePatientClick = (patient) => {
selectedPatient.value = patient
emit('patient-selected', patient)
}
return {
selectedPatient,
handlePatientClick
}
}
}
代码格式化
使用 Prettier 进行代码格式化：
npm run format
代码检查
使用 ESLint 进行代码检查：
npm run lint
通用规范
-
命名规范
- 使用有意义的变量和函数名
- Python: snake_case
- JavaScript: camelCase
- 常量: UPPER_CASE
- 类名: PascalCase
-
注释规范
- 为复杂逻辑添加注释
- 使用文档字符串描述函数和类
- 注释应该解释"为什么"而不是"是什么"
-
文件组织
- 保持文件结构清晰
- 相关功能放在同一模块
- 避免循环导入
提交规范
我们使用 Conventional Commits 规范：
提交消息格式
type(scope): description
[optional body]
[optional footer(s)]
类型 (type)
feat: 新功能fix: 修复 bugdocs: 文档更新style: 代码格式化（不影响代码运行的变动）refactor: 重构（既不是新增功能，也不是修复 bug 的代码变动）perf: 性能优化test: 增加测试chore: 构建过程或辅助工具的变动ci: CI 配置文件和脚本的变动revert: 回滚之前的提交
范围 (scope)
frontend: 前端相关backend: 后端相关database: 数据库相关device: 设备管理相关analysis: 数据分析相关ui: 用户界面相关api: API 相关config: 配置相关docs: 文档相关test: 测试相关
示例
# 新功能
git commit -m "feat(frontend): add patient search functionality"
# Bug 修复
git commit -m "fix(backend): resolve database connection timeout issue"
# 文档更新
git commit -m "docs(api): update patient management API documentation"
# 重构
git commit -m "refactor(device): simplify camera initialization logic"
Pull Request 流程
创建 Pull Request
-
Fork 仓库
- 点击 GitHub 页面右上角的 "Fork" 按钮
-
创建功能分支
git checkout -b feature/your-feature-name # 或 git checkout -b fix/your-bug-fix -
进行开发
- 编写代码
- 添加测试
- 更新文档
-
提交更改
git add . git commit -m "feat(scope): your commit message" -
推送分支
git push origin feature/your-feature-name -
创建 Pull Request
- 在 GitHub 上创建 Pull Request
- 填写详细的描述
Pull Request 模板
## 描述
简要描述这个 PR 的目的和内容。
## 更改类型
- [ ] Bug 修复
- [ ] 新功能
- [ ] 重构
- [ ] 文档更新
- [ ] 性能优化
- [ ] 其他（请说明）
## 测试
- [ ] 已添加单元测试
- [ ] 已添加集成测试
- [ ] 已手动测试
- [ ] 所有测试通过
## 检查清单
- [ ] 代码遵循项目规范
- [ ] 已添加必要的注释
- [ ] 已更新相关文档
- [ ] 没有引入新的警告
- [ ] 已测试在不同环境下的兼容性
## 相关问题
关闭 #issue_number
## 截图（如适用）
添加截图来帮助解释你的更改。
## 额外说明
添加任何其他相关信息。
代码审查
所有 Pull Request 都需要经过代码审查：
-
自动检查
- CI/CD 流水线检查
- 代码格式检查
- 测试覆盖率检查
-
人工审查
- 代码质量
- 设计合理性
- 测试完整性
- 文档完整性
-
审查标准
- 代码可读性
- 性能影响
- 安全性考虑
- 向后兼容性
问题报告
报告 Bug
使用 Bug 报告模板：
**描述 Bug**
清晰简洁地描述 bug 是什么。
**重现步骤**
重现行为的步骤：
1. 转到 '...'
2. 点击 '....'
3. 滚动到 '....'
4. 看到错误
**预期行为**
清晰简洁地描述你期望发生什么。
**截图**
如果适用，添加截图来帮助解释你的问题。
**环境信息**
- 操作系统: [例如 Windows 10]
- Python 版本: [例如 3.9.0]
- Node.js 版本: [例如 16.14.0]
- 应用版本: [例如 1.0.0]
**额外信息**
添加任何其他关于问题的信息。
报告安全问题
如果发现安全漏洞，请不要在公开的 issue 中报告。请发送邮件到 security@example.com。
功能请求
使用 功能请求模板：
**功能描述**
清晰简洁地描述你想要的功能。
**问题描述**
清晰简洁地描述问题是什么。例如：我总是感到沫丧当 [...]
**解决方案**
清晰简洁地描述你想要发生什么。
**替代方案**
清晰简洁地描述你考虑过的任何替代解决方案或功能。
**额外信息**
添加任何其他关于功能请求的信息或截图。
文档贡献
文档类型
-
用户文档
- 安装指南
- 使用教程
- 常见问题
- 故障排除
-
开发者文档
- API 文档
- 架构说明
- 贡献指南
- 代码注释
-
项目文档
- README
- CHANGELOG
- LICENSE
- 项目规划
文档规范
-
Markdown 格式
- 使用标准 Markdown 语法
- 保持一致的格式
- 使用有意义的标题
-
内容要求
- 清晰准确
- 及时更新
- 包含示例
- 考虑不同用户水平
-
图片和媒体
- 使用 SVG 格式（如可能）
- 优化文件大小
- 提供替代文本
测试指南
测试类型
-
单元测试
- 测试单个函数或方法
- 使用 pytest（Python）或 Jest（JavaScript）
- 目标覆盖率 > 80%
-
集成测试
- 测试模块间交互
- 测试 API 端点
- 测试数据库操作
-
端到端测试
- 测试完整用户流程
- 使用 Playwright 或 Cypress
- 测试关键业务场景
测试规范
# Python 测试示例
import pytest
from unittest.mock import Mock, patch
class TestPatientManager:
"""患者管理器测试类"""
@pytest.fixture
def patient_manager(self):
"""测试夹具"""
return PatientManager(":memory:")
def test_create_patient_success(self, patient_manager):
"""测试成功创建患者"""
patient_data = {
"name": "测试患者",
"age": 30,
"gender": "male"
}
patient_id = patient_manager.create_patient(patient_data)
assert patient_id is not None
assert isinstance(patient_id, int)
def test_create_patient_invalid_data(self, patient_manager):
"""测试无效数据创建患者"""
invalid_data = {"name": ""}
with pytest.raises(ValueError):
patient_manager.create_patient(invalid_data)
// JavaScript 测试示例
import { describe, it, expect, vi } from 'vitest'
import { mount } from '@vue/test-utils'
import PatientList from '@/components/PatientList.vue'
describe('PatientList', () => {
it('renders patient list correctly', () => {
const patients = [
{ id: 1, name: '患者1', age: 30 },
{ id: 2, name: '患者2', age: 25 }
]
const wrapper = mount(PatientList, {
props: { patients }
})
expect(wrapper.findAll('.patient-item')).toHaveLength(2)
expect(wrapper.text()).toContain('患者1')
expect(wrapper.text()).toContain('患者2')
})
it('emits patient-selected event when patient is clicked', async () => {
const patients = [{ id: 1, name: '患者1', age: 30 }]
const wrapper = mount(PatientList, {
props: { patients }
})
await wrapper.find('.patient-item').trigger('click')
expect(wrapper.emitted('patient-selected')).toBeTruthy()
expect(wrapper.emitted('patient-selected')[0]).toEqual([patients[0]])
})
})
运行测试
# Python 测试
cd backend
python -m pytest tests/ -v --cov=.
# JavaScript 测试
cd src/renderer
npm run test
# 所有测试
npm run test
发布流程
版本管理
我们使用语义化版本控制：
- 主版本号: 不兼容的 API 修改
- 次版本号: 向下兼容的功能性新增
- 修订号: 向下兼容的问题修正
发布步骤
-
更新版本号
# 更新 package.json 中的版本号 npm version patch|minor|major -
更新 CHANGELOG
- 记录所有重要更改
- 按类型分组（新增、更改、修复等）
-
创建发布标签
git tag -a v1.0.0 -m "Release version 1.0.0" git push origin v1.0.0 -
构建和测试
npm run build npm run test -
发布
- 创建 GitHub Release
- 上传构建产物
- 发布到包管理器（如需要）
社区支持
获取帮助
- GitHub Discussions: 一般讨论和问题
- GitHub Issues: Bug 报告和功能请求
- 邮件: dev@example.com
- 文档: 项目 Wiki
参与社区
- 回答其他用户的问题
- 参与功能讨论
- 分享使用经验
- 推广项目
致谢
感谢所有为这个项目做出贡献的开发者！
贡献者
特别感谢
- 感谢所有提供反馈和建议的用户
- 感谢开源社区提供的优秀工具和库
- 感谢医疗专业人士提供的专业指导
再次感谢您的贡献！如果您有任何问题，请随时联系我们。