openFuyao 社区 PR 和 ISSUE 规范 ​

1. Commit 信息编写规范 ​

1.1 基本格式 ​

markdown
<type>[optional scope]: <description>

1.2 类型说明 ​

  • feat: 新功能
  • fix: 修复缺陷
  • docs: 文档更新
  • style: 代码格式调整（不影响功能）
  • refactor: 代码重构
  • perf: 性能优化
  • test: 测试相关
  • chore: 构建过程或辅助工具变动
  • ci: CI 配置变更
  • build: 构建系统或外部依赖变更

1.3 编写要求 ​

  • 使用祈使句，现在时态（如："fix" 而非 "fixed" 或 "fixes"）
  • 首字母小写，不以句号结尾
  • 描述要简洁明了，说明提交目的

1.4 示例 ​

markdown
# 良好示例
feat(auth): 添加 OAuth2.0 登录支持
fix(api): 修复分页查询参数验证问题
docs: 更新 API 接口文档

# 不良示例
fixed bug
更新代码
小修改

2. PR 编写规范 ​

2.1 PR 标题规范 ​

  • 格式：<type>[scope]: 简要描述
  • 清晰描述 PR 的主要内容

2.2 PR 内容要求 ​

使用 PR 模板填写所有必填项

2.2.1 PR 类型 ​

明确选择对应的类型标签：

  • /kind bug - 修复问题
  • /kind feature - 实现需求
  • /kind documentation - 文档更新
  • /kind task - 其他任务

2.2.2 变更描述 ​

  • 清晰说明 PR 的目的和内容
  • 使用 1、2、3 点式罗列主要变更
  • 说明变更的动机和背景

2.2.3 关联 Issue ​

必须关联相关 Issue，如果没有相关 Issue，则需要先创建 Issue。如何是同一个仓库中的 Issue，请同时选择右侧的关联Issue选项中对应的 Issue

  • 修复问题：Fixes <Issue URL>
  • 实现需求：Implements <Issue URL>

2.2.4 发布说明 ​

  • 无用户影响：填写 "NONE"
  • 有用户影响：详细描述变更内容
  • 如需用户操作：包含 "action required"

2.3 保持 PR 内容干净 ​

2.3.1 单一职责原则 ​

  • 一个 PR 只解决一个问题或实现一个功能
  • 避免在一个 PR 中混合多个不相关的修改

2.3.2 Commit 整理建议 ​

建议提交前进行如下操作:

  1. Rebase 主分支：确保基于最新代码

    bash
    git fetch origin
git rebase origin/main

  2. 整理 commit 历史：

    bash
    # 合并多个相关的小commit
git rebase -i HEAD~3

# 或者使用 squash 合并
git commit --amend

  3. 禁止的情况：

    • 一个 PR 包含多个 "fix: issue" 的 commit
    • 包含无关的格式调整或空白字符修改
    • 将多个独立功能混合在一个 PR 中

3. PR 可追溯性要求 ​

3.1 Issue 关联要求 ​

必须关联以下信息之一：

  • 问题单（Bug Issue）
  • 需求单（Requirement Issue）
  • 其他相关 Issue

4. Issue 编写规范 ​

4.1 问题单（Bug）编写要求 ​

使用 template_bug.md 模板

4.1.1 标题格式 ​

markdown
【模块名称】问题简要描述

示例：【应用市场】应用详情页面加载失败

4.1.2 环境信息 ​

  • 详细描述复现环境
  • 操作系统、版本、架构等信息

4.1.3 问题描述 ​

  • 清晰描述问题现象
  • 提供详细的复现步骤
  • 包含期望结果和实际结果对比

4.1.4 Issue关联 ​

  • 推荐附上在 release-management 中的需求链接

4.2 需求单（Requirement）编写要求 ​

使用 template_requirement.md 模板

4.2.1 需求描述 ​

  • 背景和使用场景说明
  • 需求的价值和竞争力分析
  • 明确的需求类型（新增/增强/继承）

4.2.2 约束条件 ​

  • 兼容性要求
  • 技术约束
  • 交付时间和团队信息

5. 正确关闭 Issue 的规范 ​

5.1 通过 PR 自动关闭 ​

在 PR 描述中使用关键字:

markdown
Fixes <ISSUE URL>
Implements <ISSUE URL>

5.2 手动关闭条件 ​

以下情况可以手动关闭：

  • 问题无法复现且提供足够信息
  • 问题属于预期行为
  • 重复问题 <Issue URL>
  • 需求已由其他方式实现
  • 需求不再适用

5.3 关闭前检查清单 ​

  • [ ] 问题已修复并验证
  • [ ] 相关测试用例已添加
  • [ ] 文档已更新（如需要）
  • [ ] 发布说明已填写
  • [ ] 相关 PR 已合并

6. 最佳实践示例 ​

6.1 完整的 PR 流程示例 ​

markdown
# PR 标题
fix(api): 修复用户分页查询性能问题

# PR 描述
Fixes <Issue URL>

## 变更内容
1. 优化用户列表查询的数据库索引
2. 添加分页查询的性能测试用例
3. 更新 API 文档中的性能说明

## 测试验证
- [x] 单元测试通过
- [x] 性能测试显示查询时间从 2s 降低到 200ms

## 发布说明
优化用户分页查询性能，大幅减少响应时间

6.2 Issue 关闭示例 ​

markdown
# 关闭评论
已通过 PR <PR URL> 修复该问题，验证结果：
- 修复版本：v1.2.0
- 验证环境：测试环境
- 验证结果：分页查询性能提升 10 倍
- 相关 PR：<PR URL>

关闭此问题。

7. 审查要点 ​

7.1 提交前自查清单 ​

  • [ ] Commit 信息符合规范
  • [ ] PR 标题清晰准确
  • [ ] 关联了正确的 Issue
  • [ ] 代码变更单一专注
  • [ ] 测试用例完备
  • [ ] 文档更新及时
  • [ ] 发布说明填写完整