382 lines
7.6 KiB
Markdown
382 lines
7.6 KiB
Markdown
# 贡献指南
|
||
|
||
感谢您对智慧农业生产管理系统项目的关注！我们欢迎所有形式的贡献，包括但不限于代码贡献、问题反馈、文档改进和功能建议。
|
||
|
||
## 📋 目录
|
||
|
||
- [行为准则](#行为准则)
|
||
- [如何贡献](#如何贡献)
|
||
- [开发流程](#开发流程)
|
||
- [代码规范](#代码规范)
|
||
- [提交规范](#提交规范)
|
||
- [问题报告](#问题报告)
|
||
- [功能请求](#功能请求)
|
||
- [代码审查](#代码审查)
|
||
- [发布流程](#发布流程)
|
||
|
||
## 🤝 行为准则
|
||
|
||
### 我们的承诺
|
||
|
||
为了营造一个开放和友好的环境，我们作为贡献者和维护者承诺让每个人都能参与我们的项目和社区。
|
||
|
||
### 我们的标准
|
||
|
||
积极行为包括：
|
||
|
||
- 使用友好和包容的语言
|
||
- 尊重不同的观点和经验
|
||
- 优雅地接受建设性批评
|
||
- 关注对社区最有利的事情
|
||
- 对其他社区成员表示同理心
|
||
|
||
不可接受的行为包括：
|
||
|
||
- 使用性化的语言或图像
|
||
- 人身攻击或政治攻击
|
||
- 公开或私下骚扰
|
||
- 未经明确许可发布他人的私人信息
|
||
- 其他在专业环境中可能被认为不当的行为
|
||
|
||
## 🚀 如何贡献
|
||
|
||
### 1. 准备工作
|
||
|
||
```bash
|
||
# Fork 项目到您的GitHub账户
|
||
# 克隆您的fork
|
||
git clone https://github.com/your-username/agriculture-management.git
|
||
|
||
# 添加上游仓库
|
||
git remote add upstream https://github.com/original-owner/agriculture-management.git
|
||
|
||
# 安装依赖
|
||
cd agriculture-management
|
||
npm install
|
||
|
||
# 启动开发环境
|
||
npm run dev
|
||
```
|
||
|
||
### 2. 选择贡献方式
|
||
|
||
- 🐛 **报告Bug**: 发现问题并创建详细的问题报告
|
||
- 💡 **功能建议**: 提出新功能或改进建议
|
||
- 📝 **文档改进**: 完善项目文档
|
||
- 💻 **代码贡献**: 修复bug或实现新功能
|
||
|
||
## 🔄 开发流程
|
||
|
||
### 1. 创建分支
|
||
|
||
```bash
|
||
# 确保master分支是最新的
|
||
git checkout master
|
||
git pull upstream master
|
||
|
||
# 创建功能分支
|
||
git checkout -b feature/your-feature-name
|
||
# 或
|
||
git checkout -b fix/your-bug-fix
|
||
```
|
||
|
||
### 2. 开发过程
|
||
|
||
```bash
|
||
# 启用开发工具（可选）
|
||
npm run scripts:enable
|
||
|
||
# 进行开发
|
||
# ...
|
||
|
||
# 运行测试
|
||
npm run test
|
||
|
||
# 代码检查
|
||
npm run lint
|
||
|
||
# 类型检查
|
||
npm run type-check
|
||
|
||
# 格式化代码
|
||
npm run format
|
||
```
|
||
|
||
### 3. 提交更改
|
||
|
||
```bash
|
||
# 添加更改
|
||
git add .
|
||
|
||
# 提交（遵循提交规范）
|
||
git commit -m "feat(component): add new machinery status component"
|
||
|
||
# 推送到您的fork
|
||
git push origin feature/your-feature-name
|
||
```
|
||
|
||
### 4. 创建Pull Request
|
||
|
||
1. 访问GitHub上的fork页面
|
||
2. 点击"New Pull Request"
|
||
3. 选择正确的分支
|
||
4. 填写PR模板
|
||
5. 提交Pull Request
|
||
|
||
## 📏 代码规范
|
||
|
||
### TypeScript规范
|
||
|
||
```typescript
|
||
// ✅ 好的示例
|
||
interface MachineryData {
|
||
id: string
|
||
name: string
|
||
status: MachineryStatus
|
||
lastMaintenance?: Date
|
||
}
|
||
|
||
const getMachineryStatus = async (id: string): Promise<MachineryData> => {
|
||
const response = await fetch(`/api/machinery/${id}`)
|
||
return response.json()
|
||
}
|
||
|
||
// ❌ 避免的写法
|
||
const getData = (id) => {
|
||
return fetch('/api/machinery/' + id).then(r => r.json())
|
||
}
|
||
```
|
||
|
||
### React组件规范
|
||
|
||
```typescript
|
||
// ✅ 函数式组件 + TypeScript
|
||
interface MachineryCardProps {
|
||
machinery: MachineryData
|
||
onEdit?: (machinery: MachineryData) => void
|
||
className?: string
|
||
}
|
||
|
||
export const MachineryCard: React.FC<MachineryCardProps> = ({
|
||
machinery,
|
||
onEdit,
|
||
className
|
||
}) => {
|
||
const handleEdit = useCallback(() => {
|
||
onEdit?.(machinery)
|
||
}, [machinery, onEdit])
|
||
|
||
return (
|
||
<div className={cn('machinery-card', className)}>
|
||
{/* 组件内容 */}
|
||
</div>
|
||
)
|
||
}
|
||
```
|
||
|
||
### 样式规范
|
||
|
||
```typescript
|
||
// ✅ 使用Tailwind CSS + cn工具
|
||
import { cn } from '@/lib/utils'
|
||
|
||
const Button = ({ variant = 'primary', className, ...props }) => (
|
||
<button
|
||
className={cn(
|
||
'px-4 py-2 rounded-md font-medium transition-colors',
|
||
{
|
||
'bg-blue-600 text-white': variant === 'primary',
|
||
'bg-gray-200 text-gray-900': variant === 'secondary'
|
||
},
|
||
className
|
||
)}
|
||
{...props}
|
||
/>
|
||
)
|
||
```
|
||
|
||
## 📝 提交规范
|
||
|
||
### 提交格式
|
||
|
||
```
|
||
<type>(<scope>): <subject>
|
||
|
||
<body>
|
||
|
||
<footer>
|
||
```
|
||
|
||
### 提交类型
|
||
|
||
- `feat`: 新功能
|
||
- `fix`: Bug修复
|
||
- `docs`: 文档更新
|
||
- `style`: 代码格式化（不影响功能）
|
||
- `refactor`: 代码重构
|
||
- `perf`: 性能优化
|
||
- `test`: 添加或修改测试
|
||
- `chore`: 构建过程或辅助工具的变动
|
||
|
||
### 示例
|
||
|
||
```bash
|
||
# 新功能
|
||
git commit -m "feat(machinery): add real-time monitoring dashboard"
|
||
|
||
# Bug修复
|
||
git commit -m "fix(auth): resolve login validation error for special characters"
|
||
|
||
# 文档更新
|
||
git commit -m "docs(readme): update installation instructions for Windows"
|
||
|
||
# 性能优化
|
||
git commit -m "perf(machinery): optimize data loading with virtual scrolling"
|
||
```
|
||
|
||
## 🐛 问题报告
|
||
|
||
### 报告Bug
|
||
|
||
使用以下模板创建Bug报告：
|
||
|
||
```markdown
|
||
## Bug描述
|
||
简洁明了地描述Bug
|
||
|
||
## 复现步骤
|
||
1. 进入 '...'
|
||
2. 点击 '....'
|
||
3. 滚动到 '....'
|
||
4. 看到错误
|
||
|
||
## 期望行为
|
||
描述您期望发生的行为
|
||
|
||
## 实际行为
|
||
描述实际发生的行为
|
||
|
||
## 截图
|
||
如果适用，添加截图来帮助解释问题
|
||
|
||
## 环境信息
|
||
- 操作系统: [例如 iOS]
|
||
- 浏览器: [例如 chrome, safari]
|
||
- 版本: [例如 22]
|
||
|
||
## 附加信息
|
||
添加任何其他关于问题的信息
|
||
```
|
||
|
||
### 安全漏洞
|
||
|
||
如果您发现安全漏洞，请不要公开报告。请发送邮件至：security@example.com
|
||
|
||
## 💡 功能请求
|
||
|
||
### 请求新功能
|
||
|
||
```markdown
|
||
## 功能描述
|
||
简洁明了地描述您想要的功能
|
||
|
||
## 问题背景
|
||
描述这个功能要解决的问题
|
||
|
||
## 解决方案
|
||
描述您希望的解决方案
|
||
|
||
## 替代方案
|
||
描述您考虑过的其他解决方案
|
||
|
||
## 附加信息
|
||
添加任何其他关于功能请求的信息
|
||
```
|
||
|
||
## 👀 代码审查
|
||
|
||
### 审查者指南
|
||
|
||
当审查代码时，请关注：
|
||
|
||
1. **功能正确性**: 代码是否按预期工作
|
||
2. **代码质量**: 是否遵循项目规范
|
||
3. **性能影响**: 是否有性能问题
|
||
4. **安全性**: 是否存在安全隐患
|
||
5. **测试覆盖**: 是否有足够的测试
|
||
6. **文档**: 是否需要更新文档
|
||
|
||
### 审查评论规范
|
||
|
||
```markdown
|
||
# ✅ 好的评论
|
||
"建议将这个函数提取为自定义Hook，以提高复用性"
|
||
"这个变量名不够清晰，建议改为更具描述性的名称"
|
||
"考虑添加错误处理逻辑"
|
||
|
||
# ❌ 避免的评论
|
||
"这段代码不好"（过于模糊）
|
||
"重写这个"（没有具体建议）
|
||
```
|
||
|
||
### 被审查者指南
|
||
|
||
- 对建设性反馈持开放态度
|
||
- 解释您的技术决策
|
||
- 感谢审查者的时间
|
||
- 及时响应评论
|
||
|
||
## 🏷️ 发布流程
|
||
|
||
### 版本号规范
|
||
|
||
遵循 [语义化版本](https://semver.org/lang/zh-CN/)：
|
||
|
||
- `MAJOR.MINOR.PATCH`
|
||
- `MAJOR`: 不兼容的API修改
|
||
- `MINOR`: 向下兼容的功能性新增
|
||
- `PATCH`: 向下兼容的问题修正
|
||
|
||
### 发布检查清单
|
||
|
||
发布前确认：
|
||
|
||
- [ ] 所有测试通过
|
||
- [ ] 代码审查完成
|
||
- [ ] 文档已更新
|
||
- [ ] CHANGELOG已更新
|
||
- [ ] 版本号已更新
|
||
- [ ] 性能测试通过
|
||
|
||
## 🏆 贡献者认可
|
||
|
||
### 贡献者类型
|
||
|
||
- 💻 **代码贡献**: 提交代码
|
||
- 🐛 **Bug报告**: 发现并报告问题
|
||
- 💡 **功能建议**: 提出新功能想法
|
||
- 📝 **文档改进**: 完善项目文档
|
||
- 🎨 **设计贡献**: UI/UX设计改进
|
||
- 🌐 **翻译贡献**: 多语言支持
|
||
|
||
### 认可方式
|
||
|
||
- 在README中添加贡献者列表
|
||
- 在发布说明中感谢贡献者
|
||
- 颁发贡献者徽章
|
||
- 邀请加入核心团队
|
||
|
||
## 📞 联系方式
|
||
|
||
- **项目维护者**: maintainer@example.com
|
||
- **技术讨论**: GitHub Discussions
|
||
- **Bug报告**: GitHub Issues
|
||
- **安全问题**: security@example.com
|
||
|
||
## 📄 许可证
|
||
|
||
通过贡献代码，您同意您的贡献将在与项目相同的 [MIT License](LICENSE) 下获得许可。
|
||
|
||
---
|
||
|
||
感谢您的贡献！🎉 |