子仓库提交
This commit is contained in:
382
crop-x-new/CONTRIBUTING.md
Normal file
382
crop-x-new/CONTRIBUTING.md
Normal file
@@ -0,0 +1,382 @@
|
||||
# 贡献指南
|
||||
|
||||
感谢您对智慧农业生产管理系统项目的关注！我们欢迎所有形式的贡献，包括但不限于代码贡献、问题反馈、文档改进和功能建议。
|
||||
|
||||
## 📋 目录
|
||||
|
||||
- [行为准则](#行为准则)
|
||||
- [如何贡献](#如何贡献)
|
||||
- [开发流程](#开发流程)
|
||||
- [代码规范](#代码规范)
|
||||
- [提交规范](#提交规范)
|
||||
- [问题报告](#问题报告)
|
||||
- [功能请求](#功能请求)
|
||||
- [代码审查](#代码审查)
|
||||
- [发布流程](#发布流程)
|
||||
|
||||
## 🤝 行为准则
|
||||
|
||||
### 我们的承诺
|
||||
|
||||
为了营造一个开放和友好的环境，我们作为贡献者和维护者承诺让每个人都能参与我们的项目和社区。
|
||||
|
||||
### 我们的标准
|
||||
|
||||
积极行为包括：
|
||||
|
||||
- 使用友好和包容的语言
|
||||
- 尊重不同的观点和经验
|
||||
- 优雅地接受建设性批评
|
||||
- 关注对社区最有利的事情
|
||||
- 对其他社区成员表示同理心
|
||||
|
||||
不可接受的行为包括：
|
||||
|
||||
- 使用性化的语言或图像
|
||||
- 人身攻击或政治攻击
|
||||
- 公开或私下骚扰
|
||||
- 未经明确许可发布他人的私人信息
|
||||
- 其他在专业环境中可能被认为不当的行为
|
||||
|
||||
## 🚀 如何贡献
|
||||
|
||||
### 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) 下获得许可。
|
||||
|
||||
---
|
||||
|
||||
感谢您的贡献！🎉
|
||||
Reference in New Issue
Block a user