# 贡献指南

感谢您对智慧农业生产管理系统项目的关注！我们欢迎所有形式的贡献，包括但不限于代码贡献、问题反馈、文档改进和功能建议。

## 📋 目录

- [行为准则](#行为准则)
- [如何贡献](#如何贡献)
- [开发流程](#开发流程)
- [代码规范](#代码规范)
- [提交规范](#提交规范)
- [问题报告](#问题报告)
- [功能请求](#功能请求)
- [代码审查](#代码审查)
- [发布流程](#发布流程)

## 🤝 行为准则

### 我们的承诺

为了营造一个开放和友好的环境，我们作为贡献者和维护者承诺让每个人都能参与我们的项目和社区。

### 我们的标准

积极行为包括：

- 使用友好和包容的语言
- 尊重不同的观点和经验
- 优雅地接受建设性批评
- 关注对社区最有利的事情
- 对其他社区成员表示同理心

不可接受的行为包括：

- 使用性化的语言或图像
- 人身攻击或政治攻击
- 公开或私下骚扰
- 未经明确许可发布他人的私人信息
- 其他在专业环境中可能被认为不当的行为

## 🚀 如何贡献

### 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) 下获得许可。

---

感谢您的贡献！🎉