Back to Details

milestone-management

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Milestone Management

里程碑管理

Overview

概述

Milestones group issues by delivery phase or time period. They answer "what will be done by when?"
Core principle: Milestones are delivery commitments. Track them closely.
Announce at start: "I'm using milestone-management to organize work into delivery phases."
里程碑按交付阶段或时间段对议题进行分组。它们回答“在何时之前完成什么？”的问题。
核心原则： 里程碑是交付承诺，需密切跟踪。
启动时告知： “我正在使用里程碑管理将工作组织为交付阶段。”

What is a Milestone?

什么是里程碑？

A milestone is:
  • A GitHub milestone with a title, description, and optional due date
  • A collection of issues and epics targeting that delivery phase
  • A progress tracker showing completion percentage
里程碑是：
  • 带有标题、描述和可选截止日期的GitHub里程碑
  • 针对该交付阶段的议题和史诗集合
  • 显示完成百分比的进度跟踪器

Milestone vs Epic

里程碑 vs 史诗

AspectMilestoneEpic
Grouping byTime/delivery phaseFeature/capability
ScopeCross-cuttingFocused
Can containMultiple epicsRelated issues
Progress% of issues closed% of issues closed
Due dateUsually has oneUsually doesn't
An epic can be assigned to a milestone. Multiple epics can share a milestone.
维度里程碑史诗
分组依据时间/交付阶段功能/能力
范围跨领域聚焦特定方向
可包含内容多个史诗相关议题
进度计算已关闭议题占比已关闭议题占比
截止日期通常设置通常不设置
一个史诗可以被分配到一个里程碑，多个史诗可以共享同一个里程碑。

Creating a Milestone

创建里程碑

Via GitHub CLI

通过GitHub CLI创建

bash
undefined
bash
undefined

Create milestone with due date

创建带截止日期的里程碑

gh api repos/$GITHUB_OWNER/$GITHUB_REPO/milestones
-X POST
-f title="[NAME]"
-f description="[DESCRIPTION]"
-f due_on="YYYY-MM-DDTHH:MM:SSZ"
gh api repos/$GITHUB_OWNER/$GITHUB_REPO/milestones
-X POST
-f title="[NAME]"
-f description="[DESCRIPTION]"
-f due_on="YYYY-MM-DDTHH:MM:SSZ"

Create milestone without due date

创建不带截止日期的里程碑

gh api repos/$GITHUB_OWNER/$GITHUB_REPO/milestones
-X POST
-f title="[NAME]"
-f description="[DESCRIPTION]"
undefined
gh api repos/$GITHUB_OWNER/$GITHUB_REPO/milestones
-X POST
-f title="[NAME]"
-f description="[DESCRIPTION]"
undefined

Milestone Naming Conventions

里程碑命名规范

PatternExampleUse Case
Version
v1.0.0
Release milestones
Quarter
Q1 2026
Quarterly planning
Phase
Phase 1: Foundation
Initiative phases
Sprint
Sprint 23
Agile sprints
Date
2026-01 January
Monthly releases
模式示例使用场景
版本号
v1.0.0
发布里程碑
季度
Q1 2026
季度规划
阶段
Phase 1: Foundation
项目举措阶段
迭代
Sprint 23
敏捷迭代
日期
2026-01 January
月度发布

Milestone Description Template

里程碑描述模板

markdown
undefined
markdown
undefined

[MILESTONE NAME]

[MILESTONE NAME]

Goals

目标

  • [Primary goal 1]
  • [Primary goal 2]
  • [核心目标1]
  • [核心目标2]

Epics Included

包含的史诗

  • #[EPIC_1] - [Epic Title]
  • #[EPIC_2] - [Epic Title]
  • #[EPIC_1] - [史诗标题]
  • #[EPIC_2] - [史诗标题]

Key Deliverables

关键交付物

  1. [Deliverable 1]
  2. [Deliverable 2]
  3. [Deliverable 3]
  1. [交付物1]
  2. [交付物2]
  3. [交付物3]

Success Criteria

成功标准

  • [Criterion 1]
  • [Criterion 2]
  • [标准1]
  • [标准2]

Dependencies

依赖关系

  • Requires: [Previous milestone or external dependency]
  • Enables: [What this milestone unblocks]
Target Date: [DATE] Owner: [Team/Person]
undefined
  • 依赖：[前置里程碑或外部依赖]
  • 赋能：[本里程碑解锁的内容]
目标日期： [DATE] 负责人： [团队/个人]
undefined

Assigning Issues to Milestones

为里程碑分配议题

Assign During Creation

创建议题时分配

bash
gh issue create \
  --title "[Title]" \
  --milestone "[MILESTONE_NAME]" \
  --body "[Body]"
bash
gh issue create \
  --title "[Title]" \
  --milestone "[MILESTONE_NAME]" \
  --body "[Body]"

Assign Existing Issue

为现有议题分配

bash
gh issue edit [ISSUE_NUMBER] --milestone "[MILESTONE_NAME]"
bash
gh issue edit [ISSUE_NUMBER] --milestone "[MILESTONE_NAME]"

Assign Epic to Milestone

为史诗分配里程碑

bash
undefined
bash
undefined

Assign the epic tracking issue

为史诗跟踪议题分配

gh issue edit [EPIC_NUMBER] --milestone "[MILESTONE_NAME]"
gh issue edit [EPIC_NUMBER] --milestone "[MILESTONE_NAME]"

Assign all issues in the epic

为史诗下所有议题分配

gh issue list --label "epic-[NAME]" --json number --jq '.[].number' |
while read num; do gh issue edit "$num" --milestone "[MILESTONE_NAME]" done
undefined
gh issue list --label "epic-[NAME]" --json number --jq '.[].number' |
while read num; do gh issue edit "$num" --milestone "[MILESTONE_NAME]" done
undefined

Tracking Milestone Progress

跟踪里程碑进度

View Milestone Status

查看里程碑状态

bash
undefined
bash
undefined

List milestones with progress

列出带进度的里程碑

gh api repos/$GITHUB_OWNER/$GITHUB_REPO/milestones
--jq '.[] | "(.title): (.open_issues) open, (.closed_issues) closed"'
gh api repos/$GITHUB_OWNER/$GITHUB_REPO/milestones
--jq '.[] | "(.title): (.open_issues) 个未关闭, (.closed_issues) 个已关闭"'

Get specific milestone details

获取特定里程碑详情

gh api repos/$GITHUB_OWNER/$GITHUB_REPO/milestones/[NUMBER]
--jq '{title, open_issues, closed_issues, due_on, description}'
undefined
gh api repos/$GITHUB_OWNER/$GITHUB_REPO/milestones/[NUMBER]
--jq '{title, open_issues, closed_issues, due_on, description}'
undefined

List Issues in Milestone

列出里程碑中的议题

bash
undefined
bash
undefined

All issues in milestone

里程碑中所有议题

gh issue list --milestone "[MILESTONE_NAME]"
gh issue list --milestone "[MILESTONE_NAME]"

Open issues in milestone

里程碑中未关闭的议题

gh issue list --milestone "[MILESTONE_NAME]" --state open
gh issue list --milestone "[MILESTONE_NAME]" --state open

Closed issues in milestone

里程碑中已关闭的议题

gh issue list --milestone "[MILESTONE_NAME]" --state closed
undefined
gh issue list --milestone "[MILESTONE_NAME]" --state closed
undefined

Progress Report

进度报告

Generate a progress report:
bash
undefined
生成进度报告：
bash
undefined

Get milestone data

获取里程碑数据

MILESTONE_DATA=$(gh api repos/$GITHUB_OWNER/$GITHUB_REPO/milestones/[NUMBER])
TITLE=$(echo "$MILESTONE_DATA" | jq -r '.title') OPEN=$(echo "$MILESTONE_DATA" | jq -r '.open_issues') CLOSED=$(echo "$MILESTONE_DATA" | jq -r '.closed_issues') TOTAL=$((OPEN + CLOSED)) PERCENT=$((CLOSED * 100 / TOTAL)) DUE=$(echo "$MILESTONE_DATA" | jq -r '.due_on')
echo "## Milestone: $TITLE" echo "Progress: $CLOSED / $TOTAL ($PERCENT%)" echo "Open: $OPEN issues" echo "Due: $DUE"
undefined
MILESTONE_DATA=$(gh api repos/$GITHUB_OWNER/$GITHUB_REPO/milestones/[NUMBER])
TITLE=$(echo "$MILESTONE_DATA" | jq -r '.title') OPEN=$(echo "$MILESTONE_DATA" | jq -r '.open_issues') CLOSED=$(echo "$MILESTONE_DATA" | jq -r '.closed_issues') TOTAL=$((OPEN + CLOSED)) PERCENT=$((CLOSED * 100 / TOTAL)) DUE=$(echo "$MILESTONE_DATA" | jq -r '.due_on')
echo "## 里程碑: $TITLE" echo "进度: $CLOSED / $TOTAL ($PERCENT%)" echo "未关闭: $OPEN 个议题" echo "截止日期: $DUE"
undefined

Milestone Lifecycle

里程碑生命周期

┌────────────┐     ┌────────────┐     ┌────────────┐     ┌────────────┐
│  Planning  │────▶│   Active   │────▶│  Closing   │────▶│   Closed   │
└────────────┘     └────────────┘     └────────────┘     └────────────┘
     │                   │                   │                  │
     ▼                   ▼                   ▼                  ▼
  Adding              Work in            Finishing         All issues
  issues              progress           last items        resolved
┌────────────┐     ┌────────────┐     ┌────────────┐     ┌────────────┐
│  规划中    │────▶│   进行中   │────▶│   收尾中   │────▶│   已关闭   │
└────────────┘     └────────────┘     └────────────┘     └────────────┘
     │                   │                   │                  │
     ▼                   ▼                   ▼                  ▼
  添加议题              工作进行中            完成最后事项        所有议题已解决

Milestone States

里程碑状态

StateIndicators
PlanningIssues being added, 0% complete
ActiveWork in progress, 1-80% complete
ClosingFinal stretch, 80-99% complete
Closed100% complete, milestone closed
状态特征
规划中正在添加议题，完成度0%
进行中工作开展中，完成度1-80%
收尾中最后冲刺阶段，完成度80-99%
已关闭完成度100%，里程碑已关闭

Updating Milestones

更新里程碑

Update Description/Due Date

更新描述/截止日期

bash
undefined
bash
undefined

Update due date

更新截止日期

gh api repos/$GITHUB_OWNER/$GITHUB_REPO/milestones/[NUMBER]
-X PATCH
-f due_on="YYYY-MM-DDTHH:MM:SSZ"
gh api repos/$GITHUB_OWNER/$GITHUB_REPO/milestones/[NUMBER]
-X PATCH
-f due_on="YYYY-MM-DDTHH:MM:SSZ"

Update description

更新描述

gh api repos/$GITHUB_OWNER/$GITHUB_REPO/milestones/[NUMBER]
-X PATCH
-f description="[NEW_DESCRIPTION]"
undefined
gh api repos/$GITHUB_OWNER/$GITHUB_REPO/milestones/[NUMBER]
-X PATCH
-f description="[NEW_DESCRIPTION]"
undefined

Close a Milestone

关闭里程碑

bash
gh api repos/$GITHUB_OWNER/$GITHUB_REPO/milestones/[NUMBER] \
  -X PATCH \
  -f state="closed"
bash
gh api repos/$GITHUB_OWNER/$GITHUB_REPO/milestones/[NUMBER] \
  -X PATCH \
  -f state="closed"

Milestone Planning Patterns

里程碑规划模式

Initiative Phases

项目举措阶段

For large initiatives, create phase milestones:
bash
undefined
针对大型项目举措，创建阶段式里程碑：
bash
undefined

Phase 1: Foundation

阶段1：基础搭建

gh api repos/$GITHUB_OWNER/$GITHUB_REPO/milestones -X POST
-f title="[Initiative] Phase 1: Foundation"
-f description="Infrastructure and setup for [Initiative Name]"
gh api repos/$GITHUB_OWNER/$GITHUB_REPO/milestones -X POST
-f title="[项目举措] 阶段1: 基础搭建"
-f description="为[项目举措名称]搭建基础设施和环境"

Phase 2: Core Features

阶段2：核心功能

gh api repos/$GITHUB_OWNER/$GITHUB_REPO/milestones -X POST
-f title="[Initiative] Phase 2: Core Features"
-f description="Primary feature implementation"
gh api repos/$GITHUB_OWNER/$GITHUB_REPO/milestones -X POST
-f title="[项目举措] 阶段2: 核心功能"
-f description="核心功能开发"

Phase 3: Polish & Launch

阶段3：优化与发布

gh api repos/$GITHUB_OWNER/$GITHUB_REPO/milestones -X POST
-f title="[Initiative] Phase 3: Polish & Launch"
-f description="Final testing, polish, and release"
undefined
gh api repos/$GITHUB_OWNER/$GITHUB_REPO/milestones -X POST
-f title="[项目举措] 阶段3: 优化与发布"
-f description="最终测试、优化与发布"
undefined

Release Milestones

发布里程碑

For version-based releases:
bash
gh api repos/$GITHUB_OWNER/$GITHUB_REPO/milestones -X POST \
  -f title="v2.0.0" \
  -f description="Major release with [features]" \
  -f due_on="2026-03-01T00:00:00Z"
针对基于版本的发布：
bash
gh api repos/$GITHUB_OWNER/$GITHUB_REPO/milestones -X POST \
  -f title="v2.0.0" \
  -f description="包含[功能]的重大版本发布" \
  -f due_on="2026-03-01T00:00:00Z"

Quarterly Milestones

季度里程碑

For quarterly planning:
bash
gh api repos/$GITHUB_OWNER/$GITHUB_REPO/milestones -X POST \
  -f title="Q1 2026" \
  -f description="Q1 2026 deliverables" \
  -f due_on="2026-03-31T23:59:59Z"
针对季度规划：
bash
gh api repos/$GITHUB_OWNER/$GITHUB_REPO/milestones -X POST \
  -f title="Q1 2026" \
  -f description="2026年第一季度交付内容" \
  -f due_on="2026-03-31T23:59:59Z"

Handling Slippage

处理进度延误

When issues won't make a milestone:
当议题无法在里程碑内完成时：

Option 1: Move to Next Milestone

选项1：移至下一个里程碑

bash
gh issue edit [ISSUE_NUMBER] --milestone "[NEXT_MILESTONE]"
bash
gh issue edit [ISSUE_NUMBER] --milestone "[NEXT_MILESTONE]"

Option 2: Extend Milestone

选项2：延长里程碑截止日期

bash
gh api repos/$GITHUB_OWNER/$GITHUB_REPO/milestones/[NUMBER] \
  -X PATCH \
  -f due_on="[NEW_DATE]"
bash
gh api repos/$GITHUB_OWNER/$GITHUB_REPO/milestones/[NUMBER] \
  -X PATCH \
  -f due_on="[NEW_DATE]"

Option 3: Reduce Scope

选项3：缩小范围

Move non-critical issues out:
bash
undefined
将非关键议题移出：
bash
undefined

Remove from milestone (set to no milestone)

从里程碑中移除（设置为无里程碑）

gh issue edit [ISSUE_NUMBER] --milestone ""
undefined
gh issue edit [ISSUE_NUMBER] --milestone ""
undefined

Document Slippage

记录延误情况

bash
gh issue comment [EPIC_OR_INITIATIVE] --body "## Milestone Update

**Milestone:** [NAME]
**Original Due:** [DATE]
**Status:** At risk

**Issues slipping:**
- #[N] - [Reason]
- #[N] - [Reason]

**Action taken:**
- [Moved X issues to next milestone]
- [Extended deadline by Y days]
- [Descoped Z items]"
bash
gh issue comment [EPIC_OR_INITIATIVE] --body "## 里程碑更新

**里程碑：** [名称]
**原截止日期：** [日期]
**状态：** 存在风险

**延误议题：**
- #[N] - [原因]
- #[N] - [原因]

**已采取措施：**
- [将X个议题移至下一个里程碑]
- [将截止日期延长Y天]
- [移除Z个非关键项]"

Milestone Reports

里程碑报告

Weekly Status Report

每周状态报告

markdown
undefined
markdown
undefined

Milestone Status Report - [DATE]

里程碑状态报告 - [日期]

[MILESTONE 1]

[里程碑1]

  • Progress: 12/20 (60%)
  • Due: [DATE]
  • Status: 🟢 On Track
  • Blockers: None
  • 进度： 12/20（60%）
  • 截止日期： [日期]
  • 状态： 🟢 正常推进
  • 阻塞项： 无

[MILESTONE 2]

[里程碑2]

  • Progress: 3/15 (20%)
  • Due: [DATE]
  • Status: 🟡 At Risk
  • Blockers: Waiting on #123
  • 进度： 3/15（20%）
  • 截止日期： [日期]
  • 状态： 🟡 存在风险
  • 阻塞项： 等待 #123 完成

[MILESTONE 3]

[里程碑3]

  • Progress: 0/10 (0%)
  • Due: [DATE]
  • Status: ⚪ Not Started
  • Blockers: Depends on Milestone 2
undefined
  • 进度： 0/10（0%）
  • 截止日期： [日期]
  • 状态： ⚪ 未启动
  • 阻塞项： 依赖里程碑2完成
undefined

Generate Report Script

生成报告脚本

bash
echo "# Milestone Status Report - $(date +%Y-%m-%d)"
echo ""

gh api repos/$GITHUB_OWNER/$GITHUB_REPO/milestones --jq '.[] |
  "## \(.title)\n- **Progress:** \(.closed_issues)/\(.open_issues + .closed_issues)\n- **Due:** \(.due_on // "No due date")\n"'
bash
echo "# 里程碑状态报告 - $(date +%Y-%m-%d)"
echo ""

gh api repos/$GITHUB_OWNER/$GITHUB_REPO/milestones --jq '.[] |
  "## \(.title)\n- **进度：** \(.closed_issues)/\(.open_issues + .closed_issues)\n- **截止日期：** \(.due_on // "无截止日期")\n"'

Memory Integration

内存集成

bash
mcp__memory__create_entities([{
  "name": "Milestone-[NAME]",
  "entityType": "Milestone",
  "observations": [
    "Created: [DATE]",
    "Due: [DATE]",
    "Repository: $GITHUB_REPO",
    "Epics: [LIST]",
    "Issues: [COUNT]",
    "Status: [Planning/Active/Closed]"
  ]
}])
bash
mcp__memory__create_entities([{
  "name": "Milestone-[NAME]",
  "entityType": "Milestone",
  "observations": [
    "创建时间：[日期]",
    "截止日期：[日期]",
    "仓库：$GITHUB_REPO",
    "史诗：[列表]",
    "议题数量：[COUNT]",
    "状态：[规划中/进行中/已关闭]"
  ]
}])

Checklist

检查清单

  • Created milestone with clear name
  • Added description with goals
  • Set due date (if applicable)
  • Assigned epics to milestone
  • Assigned issues to milestone
  • Documented in initiative (if applicable)
  • Set up progress tracking
  • Stored in knowledge graph
  • 创建了名称清晰的里程碑
  • 添加了包含目标的描述
  • 设置了截止日期（如适用）
  • 为里程碑分配了史诗
  • 为里程碑分配了议题
  • 在项目举措中进行了记录（如适用）
  • 配置了进度跟踪
  • 存储到了知识图谱中