【项目管理】关于Issue/Milestone的使用指导

前言

本指导内容主要基于：

• 和邹欣老师的语音交流结论
• 邹欣老师《构建之法》的相关章节内容
• 现有开源项目在类似情况下的做法
• 笔者本人的项目相关经验
• 笔者本人基于课程现状的一点私货

仅为一家之言，如有偏颇或不全者，欢迎讨论或补充，感激不尽。

关于Milestone

• Milestone顾名思义，翻译成中国话叫做“里程碑”
  • 基于上述含义我们一定程度上可以将Milestone理解为一个阶段
• 对于Milestone的建立
  • 请务必按照相对独立的局部任务目标进行划分，而不是简单的以时间节点等非项目因素来划分
  • 要设置合理的周期
    • 一般周期是1-4周为限度为好
    • 对于明显过短的阶段，该考虑是否与其他阶段合并；对于明显过长的阶段，该考虑是否进行阶段的进一步细分；不过仍然务必需要满足上述基于目标进行划分的基本要求
    • 如果实在难以两全，则在基本合理的前提下，不必强求任务周期长度（简而言之：里程碑的目标性优先于时间周期性）

【太长不看版】具体且简单来说

• Milestone需要按照相对独立的局部任务目标进行划分，不要简单地基于时间来设置Milestone
• 对于软工课程
  • Alpha阶段可以划分为一个Milestone
  • 因为其是一个完整独立的阶段，且时间周期和比较合理
• 在一些常见的开源项目中，也明显体现着阶段这一特性
  • 比如这个在Gitlab官方站上的开源项目：https://gitlab.com/arl2/palaestrai/-/milestones，靠上端的几个Milestone虽然略长于四周，但是很明确的体现着阶段的意义与目标

关于Issue

• Issue顾名思义，翻译成中国话叫做“问题”
• 对于Issue的建立
  • 请务必按照相对独立的局部任务目标进行划分，而不是简单的以时间节点等非项目因素来划分；且需要以签入代码完成某实际模块为目标导向，标准为在Gitlab系统平台上有Commit/Merge Request等形式的体现
  • 要设置合理的周期
    • 一般在实际环境下，周期以小时为单位为佳。例如，在现实企业开发中一天的8小时工作，可以设置几个Issue来跟踪进度，每个Issue大约2-3小时。
    • 其他周期相关与Milestone类似，也是同样的目标性优先于时间周期性
    • 粒度划分要尽可能做到易于跟踪了解情况，但又不应细到严重影响工作手感或失去具体意义
  • 要根据分工，设置合理的Assign to，即将Issue具体分配到人；此外对于Issue其他相关的人员，也可以在Issue内容中进行@，以确保通知到相关人员。
  • 要根据任务所属阶段，关联至对应的Milestone，以确保当前Issue进度可以纳入Milestone进行计算
  • 要根据任务性质和当前状态，打上合理的标签，以方便可以在看板上快速了解当前整个项目的进展状况
• 对于Issue的后续操作
  • 在Issue下可以就问题本身展开进一步的讨论，并注意合理使用Comment和Discussion
    • Commit指评论，意为针对此问题本身的评论，不支持进一步回复等功能
    • Discussion指讨论，意为针对此问题的讨论，支持进一步回复等功能，并且对于discussion而言
      • 需要在讨论完毕后，在讨论宣告终结的那个回复上点击右上角Resolved，表示问题已经被解决
      • discussion的解决程度也是衡量issue进度的重要指标，可以直观地理解为——“问题下的Discussion未被全部解决意味着对此问题尚有需要进一步商议的问题，并需要尽快讨论敲定”
    • 因此，建议但凡是因为存在疑问或不明确之处，而需要展开讨论和商议的内容，都请使用Discussion
  • 注意与仓库内其他内容的关联
    • 例如Commit、Merge Request等，这些关键信息需要与Issue进行充分的绑定，即在Issue中可以观测到在系统层面上所建立的关联
    • 具体来说可以参考官方文档：https://docs.gitlab.com/ee/user/project/issues/managing_issues.html#closing-issues-automatically，里面对于Commit和Merge Request如何自动操作Issue有较为详细的介绍，请各小组务必认真读一读，了解一下Gitlab Issue的正确打开姿势
  • 当任务的状态或者性质发生变化时
    • 请及时更新Issue的标签
  • 对于已经解决或者完成的Issue
    • 首先确保相关联的Commit、Merge Request等是否都已经稳定（具体来说，需要确保是期望的版本，并且如果设置了CI的话需要CI也一并通过）
    • 其次确保当前Issue下的discussion是否已经被全部解决，Issue问题底部右侧区域是否显示绿色块（如果discussion数量不少于1的话）
    • 在满足上述基本要求并且确保Issue已被解决或完成的情况下，请务必记得关闭此Issue，以在系统层面上表示该Issue的终结

【太长不看版】具体且简单来说

• 一个Issue可以视为一个问题或者任务，粒度要小一些以便精准反应各部分进展状况
• Issue应该保持其问题或者任务的性质，不要基于时间来设置Issue
• Issue需要以签入代码完成某实际模块为目标导向，诸如“学***X技术”、“对接XXX需求”等没有代码体现的内容不应作为Issue
• Issue的维护是一个完整连贯的过程，请善用Gitlab平台本身的一系列机制以达成更好的效果
• Issue讲究实事求是，情况有变则写清楚原因后增删即可
• 考虑到可能对长远一些的内容做不到精确规划，建议先以Issue的形式做粗略规划，后续根据实际情况再做扩充