开发管理规范

[ZCShou]

简介

本文档系统梳理了 AxVisor 项目的开发管理方法，明确以 GitHub 的 Project、Milestone、Issue、Discussion 等功能为核心，构建高效的开源项目协作开发流程。

其中详细介绍了各功能模块的作用及其协同方式，阐述了如何通过 Project 实现跨仓库任务整合、用 Milestone 聚焦阶段目标、以 Issue 作为任务和问题的基本单元，并借助 Discussion 进行知识共享和开发计划制定。

此外，该文档中还明确了开发过程中的行为准则、任务拆分、过程记录、版本发布等规范编写要求及存放方式，旨在减轻开发人员负担、集中问题记录、提升团队协作效率，为多仓库、多团队的开源项目提供完整的开发管理方案。

Github

Github 的核心架构以仓库（Repository） 为基础单元，所有功能均围绕仓库展开延伸。具体而言，借助 Project（项目看板） 可直观规划任务流程，Milestones（里程碑） 能设定阶段性目标，Issues（议题） 可追踪 bug 修复与功能开发，Discussions（讨论区） 则方便社区成员交流协作。这些功能的协同使用，足以覆盖开源项目从任务分配、进度跟踪到社区互动的全流程管理需求。完整的组织结构框图如下所示。

从协同逻辑来看，Issues 是连接 Project 和 Milestone 的 “原子单元”。Project 通过整合跨仓库 Issues 实现全局流程管理，Milestone 则通过聚合同仓库 Issues 聚焦阶段目标。而 Issues 自身的状态、关系和讨论记录，则让这两种管理方式都能落地到具体的开发细节中，从而在全局流程和阶段目标中同时被跟踪，确保问题及时解决。

Repository

GitHub 的仓库是项目代码与开发过程的核心载体，提供了从代码存储到协作开发的完整工具链。其核心功能是代码版本控制，同时，Github 为仓库提供了项目管理相关工具（Project、Milestone、Issue）、协作与沟通机制（Discussion、Wiki）、自动化与集成能力（Actions、 Webhook）、代码质量保障（PR、Review）、发布与分发（Release、Pages）、安全与合规（安全扫描、社区规范）、数据分析与洞察（Insights 面板、贡献者统计）等一系列功能。

Project

Project 本身并不强制绑定到仓库，而是属于个人或者组织，不同的仓库可以共用同一个 Project，它可以将不同仓库的 Issues 组织在一起提供管理。这种跨仓库整合能力对多仓库协作项目尤为重要：例如一个前端仓库的 “页面适配” Issue、后端仓库的 “接口开发” Issue，以及文档仓库的 “使用说明更新” Issue，可被统一纳入同一个 Project 中，实现全流程任务的集中追踪。

Project 本身是一个看板（Kanban）风格的任务管理工具，同时提供了甘特图、表格等视图，满足不同场景下的任务跟踪需求。例如看板视图适合敏捷开发中的迭代管理，甘特图可直观展示任务时间线与依赖关系，表格视图则便于数据化筛选和批量编辑。

Project 与 Issues、Pull Requests (PR)、仓库深度集成，支持直接将 Issues 或 PR 拖拽至任务看板，且当关联的 Issues/PR 状态更新（如从 “待处理” 改为 “已合并”）时，Project 中的对应任务会自动同步状态，减少手动操作成本。

Milestones

GitHub 的 Milestone 主要用于指定仓库的 Issues 和 Pull Requests (PRs) 的版本或阶段管理，是围绕时间节点或目标成果的任务聚合工具。开发团队可创建阶段性的 Milestone，并将相关的开发任务（Issues）和代码提交（PRs）统一关联，清晰界定某一阶段的工作范围。

每个仓库的 Milestones 是独立的，它只能组织当前仓库里的各个 Issues 来提供管理，无法跨仓库关联内容。这种仓库内的独立性使其更适合聚焦单一项目的阶段性目标。

Milestone 还具备以下核心特性，辅助精细化管理：

• 进度可视化：自动统计关联的 Issues/PRs 总数、已完成数量及占比（如 “10 个任务中 7 个已关闭”），并以进度条直观展示，便于快速掌握阶段完成情况。

• 时间维度管理：支持设置 “截止日期”，系统会在临近截止时发送提醒，帮助团队把控时间节点；同时可通过 “预计完成时间” 与实际进度对比，及时发现延期风险。

• 筛选与追踪：在仓库的 Issues 或 PRs 列表中，可通过 Milestone 筛选功能快速定位某一阶段的任务，方便回溯或跟进历史工作。

• 关联联动：当 Milestone 中的所有关联任务（Issues/PRs）被标记为 “已关闭” 时，该 Milestone 可手动标记为 “已完成”，形成闭环管理；若任务状态变更（如某 Issue 从 “进行中” 改为 “已解决”），Milestone 的进度会实时更新。

由于 Milestone 与仓库强绑定，其更适合单一仓库的阶段性目标管理，与跨仓库、灵活视图的 Project 形成互补，前者聚焦 “仓库内的版本 / 阶段闭环”，后者侧重 “多仓库的全局流程协同”，共同支撑从细节任务到整体项目的全链路管理需求。

Issues

Issues 是 Project 和 Milestones 管理的基本单元，每个仓库的 Issues 是一个独立的列表，默认情况下无法直接跨仓库关联内容（如直接引用其他仓库 Issue 作为依赖）。

Issues 其本质是项目开发中各类事务的载体，不仅分为 Task（任务）、BUG（漏洞）等基础类型，还可根据团队需求自定义类型（如 “需求建议”“文档优化”“性能问题” 等），甚至通过标签（Labels）进一步细分，实现更精细的分类管理。

Issues 本身支持关联 GitHub Project 和 Milestone 的方式来提供开发任务和目标的管理及跟踪，而 Issues 自身的丰富属性则为这种管理提供了基础支撑：

• 状态流转：Issues 包含 “打开”“关闭”“待分配”“已解决” 等状态，可随开发流程动态更新，Project 的看板视图可直接映射这些状态，Milestone 则通过状态统计判断阶段进度。

• 讨论协作：Issues 内置评论区，团队成员可直接在其中沟通细节（如 “这个 BUG 复现步骤是否完整？”），还能 @ 相关人员提醒关注，避免信息分散在外部工具中。

• 时间与负责人：可指定 “创建者”“负责人”“截止日期” 等信息，明确任务权责与时间要求，为 Project 的自动化规则和 Milestone 的进度追踪提供数据基础。

Issues 作为最基础的事务载体，其灵活的类型定义、丰富的属性和协作功能，使得 Project 和 Milestone 能够实现从宏观管理到微观执行的无缝衔接，成为 GitHub 生态中项目协作的核心枢纽。

Discussions

Discussion 可以作为仓库的一个独立区域，由仓库管理员或项目维护者在仓库的设置中启用。此外，组织所有者可以为整个组织启用 Discussion 功能，在启用时，需要选择一个组织内的仓库作为源仓库，讨论内容会同时显示在组织的 Discussion 页面和源仓库的 Discussion 页面。个人没有独立的 Discussion 空间，需依托于仓库或组织来参与 Discussion。

GitHub 的 Discussions 是一个团队协作与知识共享的平台，旨在补充 Issues 的功能局限，为项目社区提供更灵活的交流空间。通常用作功能讨论、经验分享、提问与解答等作用，也有很多仓库用 Discussion 发布版本更新、路线图等重要通知。

开发管理要求

我们的开发管理以 Github 的 Project、Milestones、issue、discussion 作为核心来组织整个开发过程。目的之一是减少开发人员的工作量，使开发人员可以关注开发任务本身，而不是去各个不同的地方填写各种记录，其次是将开发过程中遇到的问题尽量集中存放，以便后续开发者或者学习人员可以在一个地方获取最多的有用信息！

Code of Conduct

针对开发过程，我们需要建立相关行为准则以及一些开发标准。相关标准，例如本开发管理规范、阶段目标计划、Crate 发布相关标准要求等等，文档存放到 Discussion 的 Code of Conduct 分类中。

仓库

目前，AxVisor 的开发主要涉及 axvisor 和一些组件仓库（详见 axvisor-crates） 以及 doc 这个文档仓库等一众仓库。他们共用 ArceOS Tasks 这个 Project 来组织所有的开发任务。而 axvisor 和 doc 中各有自己的 Milestone 来追踪阶段目标。

开发计划

在每个阶段之初，负责人会在 Discussion 中制定项目开发计划，并指定为 Roadmap 分类。由于目前，我们的仓库有多个，在单一仓库 Issue 中建立开发计划并不合适，而 Discussion 作为 Issue 的补充，具备了作为开发计划的基本功能，进而开发计划并不绑定到任何仓库，而是作为所有仓库的总计划。

任务根据功能分类整理，格式：[可选 Mark] 任务名字（对应的 ISSUE）@负责人，示例：✨ 制定 7 月阶段计划（https://github.com/orgs/arceos-hypervisor/discussions/198） @ZCShou。 注意，对于本周完成任务，以 ✨ 表示标识出来！

在开发计划中列出要做的具体工作目标，并添加复选框以标识是否完成。开发计划中的目标是比较笼统的一个描述，通常会被拆分为具体的任务由专人负责实现。

1. 开发目标任务通常会涉及多个仓库！

2. 任务可以通过 @ 指定开发人员

创建 Project

开开阶段之初，负责人会在 Project 中创建开发计划对应的 Project，后续创建任务时，务必选择对应的 Project 名字。Project 并不绑定到任何仓库，而是作为所有仓库的总的项目管理工具，其中汇集不同仓库的 Issue。

1. 通过不同的试图来查看内容

2. 明确任务的开始时间和结束时间

开发任务

开发任务以 Issue 的形式（以任务类型区分）被拆分到不同的仓库中（但是开发人员可以通过 Project 集中进行查看）。

作为任务，我们需要认真填写 Issue 的某些字段，如下图所示，1 ~ 6 均为必填内容

子任务

对于周期比较长或者比较复杂的任务，任务的负责人负责在任务中的 sub-issue 中拆分子任务，子任务确保一到两周可以完成，其内容填写与主任务要求一致！

过程记录

在开发过程中遇到的任何问题时，要求将问题以 Comment 的形式提交到对应的 Issue 下面。当完成一个 Issue 之后，建议在 Issue 中以评论的形式列出相关 Commit 的 HASH 作为自己任务的记录，然后关闭 Issue 即可

里程碑

将不同的任务组合为一个里程碑，进一步跟踪开发进度。在阶段之初，负责人会创建阶段里程碑，并明确里程碑目标，后续创建任务时，务必选择对应的里程碑

版本发布

所有仓库必须以 TAG 的形式进行发布，发布方式是使用仓库对应的 Release 功能来实现。