# 软件工程

# GitHub Projects + Issues + PR 管理制度正式版

GitHub Projects + Issues + PR 管理制度正式版
1. 总则
本制度适用于公司所有以 GitHub 为研发协作平台的项目、仓库和研发团队，用于规范需求管理、任务编排、代码评审、合并发布与进度追踪。GitHub Projects 用于承载项目视图与状态流转，Issues 用于承载任务与缺陷，PR 用于承载代码变更与交付审查。

本制度的目标是建立“需求可追踪、任务可分配、代码可审查、状态可回溯、交付可验收”的研发闭环。GitHub Projects 支持用表格、看板和路线图视图管理 Issues 与 PR，并可通过自定义字段、自动化和模板适配团队流程。

2. 适用范围
本制度适用于产品需求、研发任务、缺陷修复、技术债务、版本发布、紧急修复等所有需要进入研发协作流程的事项。所有进入研发执行的工作项，原则上必须以 Issue 形式创建，并绑定到对应 Project 中进行管理。

以下场景也纳入本制度：跨团队协作、外包协作、线上事故处理、发布窗口管理、架构治理、CI/CD 改进等。对于仅需讨论不需执行的内容，应使用 Discussion 或内部文档，不得占用 Issue 队列。

3. 角色定义
项目负责人负责需求排序、版本目标、资源协调和最终验收。技术负责人负责技术方案、任务拆分、代码质量和发布决策。开发人员负责实现、联调、测试和 PR 提交。Reviewer负责代码审查和合并把关。项目管理员负责 Projects 配置、字段维护、模板、自动化和权限治理。

每个 Issue 必须指定一个主负责人；每个 PR 必须指定至少一个主要开发者和一个 Reviewer。若任务涉及多团队协作，项目负责人应明确接口人，避免出现无人负责或多头负责。

4. 组织原则
所有研发工作以 GitHub 内数据为唯一工作事实来源，禁止在聊天软件、口头沟通或私有备忘中替代正式任务记录。项目状态、负责人、优先级、截止时间和验收结果，必须统一记录在 Project 或关联的 Issue/PR 中。

项目管理应遵循“小粒度、可验证、可回退、可审计”的原则。GitHub Projects 可以通过筛选、分组和自定义字段管理 backlog、迭代和路线图，因此应优先将任务拆分到可在一个迭代内完成的粒度。

5. Project 规范
每个团队至少维护一个主 Project，作为团队总看板；如有多个产品线，可按产品或版本拆分为多个 Project。Project 必须至少包含以下视图：Backlog 视图、迭代视图、执行看板、发布视图。

Project 必填字段如下：

字段	说明	规则
Status	工作状态	必须包含 Backlog、Ready、In Progress、Review、Blocked、Done
Priority	优先级	必须分级，建议 P0-P3
Iteration	迭代归属	必须绑定当前迭代或版本
Owner	主负责人	必填且唯一
Type	类型	Feature、Bug、Tech Debt、Ops 等
Due date	截止时间	有明确交付承诺时填写
Project 中的字段设计应保持稳定，避免频繁改名或增删导致历史数据失效。GitHub Projects 支持自定义字段和自动化，因此字段应尽量少而精，保证整个团队都能一致使用。

6. Issue 规范
Issue 是任务单，不是聊天记录，也不是临时想法记录。每个 Issue 必须只描述一个清晰目标，具备背景、目标、范围、验收标准、依赖关系和负责人。

Issue 标题建议采用统一前缀：

feat: 功能说明

fix: 缺陷说明

refactor: 重构说明

chore: 运维或杂项

tech: 技术治理

Issue 正文必须包含以下内容：

背景说明。

目标说明。

影响范围。

验收标准。

风险与依赖。

负责人。

截止时间，如有。

Issue 创建后应尽快补充标签、优先级和关联里程碑或迭代，保证进入 Projects 后可直接进入排期。

7. Issue 生命周期
Issue 默认生命周期如下：Backlog -> Ready -> In Progress -> Review -> Done。如存在阻塞，则进入 Blocked 状态，并标注阻塞原因、依赖对象和预计恢复时间。

状态定义如下：

Backlog：已收集但未排期。

Ready：已确认可执行，等待开发。

In Progress：已开始实现。

Review：已提交 PR，等待审核。

Blocked：受外部因素阻塞。

Done：已验收完成并关闭。

除项目负责人或技术负责人批准外，不得跳过 Ready 直接进入 In Progress。Blocked 状态超过两个工作日未解除的，必须在例会上同步原因和处理计划。

8. PR 规范
PR 是代码变更的交付单，也是代码审查和发布控制的核心对象。每个 PR 必须由分支提交，不得直接向主分支提交代码；PR 标题和描述必须说明解决了什么问题、如何验证、是否有风险。

PR 必填内容如下：

关联 Issue 编号。

变更摘要。

测试结果。

风险说明。

回滚方案。

截图、日志或示例，如适用。

PR 命名建议与 Issue 保持一致，例如 feat: add retry for payment page。对于较大的功能，应拆分为多个逻辑清晰的 PR，避免一个 PR 混合大量无关改动。

9. 分支规范
建议采用以下分支模型：

main：稳定发布分支。

dev：日常集成分支。

feature/*：功能开发分支。

bugfix/*：缺陷修复分支。

hotfix/*：紧急修复分支。

开发分支必须从指定基线分支拉出，不得直接在 main 上开发。所有代码修改必须通过 PR 合并进入目标分支，任何绕过审查的直接合并均视为违规。

紧急修复允许缩短评审链路，但不得取消 PR、不得取消最小验证、不得取消关联记录。紧急修复完成后必须补齐变更说明、回顾和必要的测试记录。

10. 评审规范
PR 至少需要一名 Reviewer 审核，高风险模块、核心链路、数据库变更、权限变更等场景建议双人审核。Review 重点检查正确性、可维护性、性能、回归风险和测试覆盖，不以“看过了”作为审核结论。

Review 规则如下：

审核意见应具体到文件、函数或行为。

存在阻断性问题时，必须明确标记为需要修改后再合并。

Reviewer 不得长期无响应，超过约定时限需自动升级提醒。

对争议性修改，应先同步讨论再决定是否合并。

11. 自动化规范
GitHub Projects 支持自动化状态更新、字段更新和项目项管理，团队应优先通过自动化减少人工维护成本。

建议配置以下自动化：

Issue 创建后自动加入 Backlog。

Issue 打上 ready 标签后自动转入 Ready。

PR 创建后自动切换 Review。

PR 合并后关联 Issue 自动关闭。

Issue 关闭后自动标记 Done。

blocked 标签自动切换 Blocked。

长时间无更新的任务自动提醒。

如团队规模较大，可进一步使用 GitHub Actions 执行测试、Lint、通知和状态同步。自动化规则应优先服务于状态流转，而不是增加额外的管理负担。

12. 权限与安全
GitHub 作为任务编排系统时，必须同时考虑仓库权限、Project 可见性、组织成员分组和审计能力。企业级 GitHub 支持组织层权限、审计和协作能力，但仍应坚持最小权限原则。

安全要求如下：

仅授予完成工作所需的最低权限。

敏感仓库与普通仓库分离。

开启 2FA、SSO 和必要的审计日志。

禁止在 Issue/PR 中提交密钥、密码、令牌和敏感客户信息。

定期复核成员权限和外部协作者名单。

若项目涉及高敏感数据，需额外规定代码仓库、Issue 内容、讨论区和附件的保密级别，必要时采用私有仓库或更严格的访问控制。

13. 日常运行
团队应建立固定节奏来运行这套制度：

每日：检查本日阻塞项、Review 队列和高优先级任务。

每周：梳理 backlog、确认迭代容量、调整优先级。

每迭代：计划、评审、回顾、问题复盘。

每月：复查模板、字段、自动化和权限。

建议关注的核心指标包括：任务平均交付周期、Review 等待时间、Blocked 数量、迭代完成率、PR 合并周期。GitHub Projects 可用视图和图表辅助这些统计与观察。

14. 违规处理
以下行为视为流程违规：

直接向主分支提交代码。

不关联 Issue 即发起 PR。

Issue 缺少验收标准就进入开发。

在聊天中口头安排工作但不入 Project。

在 Issue/PR 中记录敏感信息。

长期阻塞不更新状态。

对于首次轻微违规，由项目负责人提醒并补正；重复违规则由技术负责人或项目负责人进行流程纠正，必要时暂停合并权限或提升审批级别。

15. 附则
本制度由研发负责人和项目管理负责人共同维护，建议每季度评审一次，结合团队规模、项目复杂度和工具能力进行修订。GitHub Projects、Issues 和 PR 本身强调灵活性，因此制度应明确底线规则，但保留对具体工作法的适配空间。

# 三件套 《Issue 模板》 Bug 专用模板（可选）  《PR 模板》 《Projects 字段设计表》

下面给你一套可以直接落到仓库里的三件套，格式已经按 GitHub 官方推荐的模板/字段写好，你可以按需微调后直接放到 `.github/` 目录和 Projects 中使用。 [docs.github](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository)

***

## 一、《Issue 模板》

### 1. 使用方式说明

建议使用 GitHub 的 Issue Forms（YAML）形式，这样可以强制结构化输入。模板文件需要放在仓库的 `.github/ISSUE_TEMPLATE` 目录下，并以 `*.yml` 命名。 [rewind](https://rewind.com/blog/best-practices-for-using-github-issues/)
可以为不同类型任务配置多种模板，例如「功能需求」「缺陷报告」「技术债/重构」，下面示例以通用研发团队为主。 [github](https://github.com/stevemao/github-issue-templates)

### 2. 通用 Issue 表单模板（YAML）

文件路径示例：`.github/ISSUE_TEMPLATE/general.yml`。 [youtube](https://www.youtube.com/watch?v=hNs5Gg_fEEs)

```yml
name: 通用任务 / General Task
description: 创建功能需求、技术任务或运维任务
title: "[feat] 标题：请简要概括任务目标"
labels: ["triage"]
assignees: []
body:
  - type: dropdown
    id: type
    attributes:
      label: 任务类型 / Type
      description: 请选择任务类型
      options:
        - Feature
        - Bug
        - Tech Debt
        - Ops
    validations:
      required: true

  - type: input
    id: background
    attributes:
      label: 背景 / Background
      description: 请简要说明当前问题或业务背景
      placeholder: 当前存在什么问题或机会？
    validations:
      required: true

  - type: textarea
    id: goal
    attributes:
      label: 目标与结果 / Goal & Outcome
      description: 需要达到什么目标？期望的可观察结果是什么？
      placeholder: 明确描述交付完成后，应看到什么可验证结果
    validations:
      required: true

  - type: textarea
    id: acceptance
    attributes:
      label: 验收标准 / Acceptance Criteria
      description: 列出可验证的验收点
      placeholder: |
        - [ ] 条件 1
        - [ ] 条件 2
        - [ ] 条件 3
    validations:
      required: true

  - type: textarea
    id: impact
    attributes:
      label: 影响范围 / Impact Scope
      description: 该任务影响哪些系统、模块、用户？
      placeholder: 列出受影响的服务、模块、接口或用户类型
    validations:
      required: false

  - type: textarea
    id: dependencies
    attributes:
      label: 依赖与前置条件 / Dependencies
      description: 该任务依赖哪些其他任务、决策或资源？
      placeholder: 例如：依赖某接口、其他团队、配置、第三方服务
    validations:
      required: false

  - type: input
    id: due_date
    attributes:
      label: 期望完成时间 / Expected Due Date
      description: 如有明确交付承诺，请填写 YYYY-MM-DD
      placeholder: 2026-07-31
    validations:
      required: false

  - type: textarea
    id: extra
    attributes:
      label: 备注 / Notes
      description: 其他需要说明的事项（包括风险、备选方案等）
      placeholder: 补充说明、风险、补充链接、参考文档等
    validations:
      required: false
```

### 3. Bug 专用模板（可选）

文件路径示例：`.github/ISSUE_TEMPLATE/bug.yml`。 [github](https://github.com/orgs/community/discussions/147722)

```yml
name: 缺陷报告 / Bug Report
description: 报告系统缺陷或异常行为
title: "[bug] 标题：简要描述异常现象"
labels: ["bug", "triage"]
assignees: []
body:
  - type: textarea
    id: description
    attributes:
      label: 问题描述 / Description
      description: 清晰简洁地描述问题
      placeholder: 出现了什么问题，与预期有什么差异？
    validations:
      required: true

  - type: textarea
    id: steps
    attributes:
      label: 复现步骤 / Steps to Reproduce
      description: 列出复现问题的具体步骤
      placeholder: |
        1. 步骤一
        2. 步骤二
        3. ...
    validations:
      required: true

  - type: textarea
    id: expected
    attributes:
      label: 期望行为 / Expected Behavior
      description: 说明你期望发生什么
    validations:
      required: true

  - type: textarea
    id: actual
    attributes:
      label: 实际行为 / Actual Behavior
      description: 说明实际发生了什么
    validations:
      required: true

  - type: textarea
    id: env
    attributes:
      label: 环境信息 / Environment
      description: 包括操作系统、浏览器/客户端版本、分支、版本号等
      placeholder: |
        - OS:
        - Browser/Client:
        - Branch/Version:
    validations:
      required: true

  - type: textarea
    id: logs
    attributes:
      label: 日志与截图 / Logs & Screenshots
      description: 请粘贴相关日志、错误信息或上传截图（脱敏后）
    validations:
      required: false
```

这些模板可以根据团队偏好进一步扩展，例如添加「安全等级」「模块」「Story Points」等字段。 [unicef.github](https://unicef.github.io/inventory/dpg-indicators/8/project-management/issue-templates/)

***

## 二、《PR 模板》

### 1. 使用方式说明

PR 模板建议放置在 `.github/PULL_REQUEST_TEMPLATE.md` 文件，GitHub 会自动在新建 PR 时预填内容，便于规范化信息。 [graphite](https://graphite.com/guides/comprehensive-checklist-github-pr-template)
模板应包括：关联工作项、变更说明、验证步骤、风险、回滚策略和检查项等。 [microsoft.github](https://microsoft.github.io/code-with-engineering-playbook/code-reviews/pull-request-template/)

### 2. 标准 PR 模板（Markdown）

文件路径：`.github/PULL_REQUEST_TEMPLATE.md`。 [microsoft.github](https://microsoft.github.io/code-with-engineering-playbook/code-reviews/pull-request-template/)

```markdown
# 关联 Issue / Related Issues

- 关闭/关联的 Issue：
  - Closes #123
  - Relates to #456

# 变更说明 / Description

> 简要说明本次变更的目的、背景和主要内容。

- 背景：
- 主要变更点：
  - xxx
  - xxx

# 影响范围 / Impact

> 说明本次变更影响到的模块、系统或用户。

- 受影响模块：
- 受影响接口/服务：
- 兼容性说明：

# 验证与测试 / Testing

> 列出已经执行的测试以及结果。

- [ ] 单元测试
- [ ] 集成测试
- [ ] 手工验证
- 测试说明：
  - 环境：
  - 测试步骤：
  - 结果摘要：

# 回滚方案 / Rollback Plan

> 如果上线后出现问题，如何快速回滚？

- 回滚方式：
- 回滚依赖：
- 回滚风险：

# 安全与风险 / Security & Risks

> 是否涉及安全、权限、数据迁移或大规模变更？

- [ ] 涉及权限变更
- [ ] 涉及数据结构/迁移
- [ ] 涉及第三方服务
- 风险说明：
- 缓解措施：

# Checklist

> 提交前请自检以下项目。

- [ ] 代码通过本地编译/构建
- [ ] 通过基础自动化测试（CI）
- [ ] 已自查并修复明显警告/代码味道
- [ ] 变更范围尽可能小且聚焦
- [ ] 文档/配置已更新（如适用）
- [ ] 未包含敏感信息（密钥、密码等）

# 其他信息 / Additional Context

> 任何有助于 Reviewer 理解本次变更的信息、链接或截图。

- 设计文档/需求文档链接：
- 截图：
- 其他：
```

可根据不同项目增加模块字段，如「前端/后端」「服务名称」「数据库类型」「feature flag 名称」等，使 Reviewer 能快速建立上下文。 [reddit](https://www.reddit.com/r/ExperiencedDevs/comments/142n5ea/what_do_you_think_should_be_the_standard_for_pull/)

***

## 三、《Projects 字段设计表》

### 1. 字段设计原则

GitHub Projects 支持通过自定义字段为 Issues 和 PR 添加迭代、优先级、故事点、日期、备注等元数据，用于在表格、看板和路线图视图中筛选、分组和排序。 [docs.github](https://docs.github.com/issues/planning-and-tracking-with-projects/learning-about-projects/about-projects)
字段要尽量少而关键，保证所有团队成员理解一致，避免同类信息重复出现在多个字段。 [docs.github](https://docs.github.com/enterprise-cloud@latest/issues/planning-and-tracking-with-projects/learning-about-projects/best-practices-for-projects)

### 2. 推荐字段列表

下面是一份可直接用于团队 Project 的字段设计表，你可以在 Project 的「Settings → Fields」中按表创建。 [docs.github](https://docs.github.com/enterprise-cloud@latest/issues/planning-and-tracking-with-projects/learning-about-projects/best-practices-for-projects)

| 字段名 | 类型 | 示例值 | 用途说明 |
|---|---|---|---|
| Status | 单选（枚举） | Backlog / Ready / In Progress / Review / Blocked / Done | 统一任务状态流转 |
| Priority | 单选（枚举） | P0 / P1 / P2 / P3 | 控制任务优先级 |
| Iteration | 单选（枚举）或迭代 | 2026-W27 / 2026.07-Sprint1 | 绑定迭代或版本 |
| Type | 单选（枚举） | Feature / Bug / Tech Debt / Ops | 区分任务类型 |
| Owner | 用户 | @username | 任务主负责人 |
| Story Points | 数字 | 1 / 2 / 3 / 5 / 8 | 估算工作量（可选） |
| Component | 单选（枚举） | Web / API / DB / Infra | 模块/组件归类 |
| Due Date | 日期 | 2026-07-31 | 承诺交付日期 |
| Created At | 系统字段 | 自动 | 初始创建日期 |
| Updated At | 系统字段 | 自动 | 最近更新时间 |
| Risk Level | 单选（枚举） | Low / Medium / High | 风险等级（可选） |
| Block Reason | 文本 | 等待接口 / 需求不明等 | 阻塞说明（可选） |

其中 Status、Priority、Iteration、Owner 是强建议必配，Story Points 和 Component 可根据团队敏捷实践程度选择是否启用。 [github](https://github.com/features/issues)

### 3. 视图建议

利用上述字段，可以在 Projects 中创建多个视图，以支持不同角色使用： [docs.github](https://docs.github.com/issues/planning-and-tracking-with-projects/learning-about-projects/about-projects)

- Backlog 视图：过滤 Status = Backlog / Ready，按 Priority 降序排序。
- 迭代视图：过滤特定 Iteration，按 Status 分组，适合迭代执行跟踪。
- 看板视图：按 Status 分组，限制 In Progress 列的 WIP（通过团队约定执行）。
- 路线图视图：使用表格或路线图 layout，按 Due Date 排序，看版本级目标。
- 风险视图：过滤 Risk Level = High 或 Blocked，供负责人重点关注。

Project 视图可以按用户、模块或类型进行过滤和分组，用于不同层级管理：例如「按 Owner 分组的个人待办视图」「按 Type 分组的 Bug/Feature 列表」等。 [github](https://github.com/features/issues)

***

如果你愿意，我可以帮你把这三件套再组合成一个仓库根目录的 `CONTRIBUTING.md` 示例，把“怎么提 Issue / 怎么提 PR / 怎么在 Project 中看自己任务”写成一份面向开发同事的使用指南。