majiayu000 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
Milestone vs Epic
| Aspect | Milestone | Epic |
|---|---|---|
| Grouping by | Time/delivery phase | Feature/capability |
| Scope | Cross-cutting | Focused |
| Can contain | Multiple epics | Related issues |
| Progress | % of issues closed | % of issues closed |
| Due date | Usually has one | Usually doesn't |
An epic can be assigned to a milestone. Multiple epics can share a milestone.
Creating a Milestone
Via GitHub CLI
# 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"
# Create milestone without due date
gh api repos/$GITHUB_OWNER/$GITHUB_REPO/milestones \
-X POST \
-f title="[NAME]" \
-f description="[DESCRIPTION]"
Milestone Naming Conventions
| Pattern | Example | Use 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 |
Milestone Description Template
## [MILESTONE NAME]
### Goals
- [Primary goal 1]
- [Primary goal 2]
### Epics Included
- #[EPIC_1] - [Epic Title]
- #[EPIC_2] - [Epic Title]
### Key Deliverables
1. [Deliverable 1]
2. [Deliverable 2]
3. [Deliverable 3]
### Success Criteria
- [ ] [Criterion 1]
- [ ] [Criterion 2]
### Dependencies
- Requires: [Previous milestone or external dependency]
- Enables: [What this milestone unblocks]
---
**Target Date:** [DATE]
**Owner:** [Team/Person]
Assigning Issues to Milestones
Assign During Creation
gh issue create \
--title "[Title]" \
--milestone "[MILESTONE_NAME]" \
--body "[Body]"
Assign Existing Issue
gh issue edit [ISSUE_NUMBER] --milestone "[MILESTONE_NAME]"
Assign Epic to Milestone
# Assign the epic tracking issue
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
Tracking Milestone Progress
View Milestone Status
# List milestones with progress
gh api repos/$GITHUB_OWNER/$GITHUB_REPO/milestones \
--jq '.[] | "\(.title): \(.open_issues) open, \(.closed_issues) closed"'
# Get specific milestone details
gh api repos/$GITHUB_OWNER/$GITHUB_REPO/milestones/[NUMBER] \
--jq '{title, open_issues, closed_issues, due_on, description}'
List Issues in Milestone
# All issues in milestone
gh issue list --milestone "[MILESTONE_NAME]"
# Open issues in milestone
gh issue list --milestone "[MILESTONE_NAME]" --state open
# Closed issues in milestone
gh issue list --milestone "[MILESTONE_NAME]" --state closed
Progress Report
Generate a progress report:
# 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"
Milestone Lifecycle
┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐
│ Planning │────▶│ Active │────▶│ Closing │────▶│ Closed │
└────────────┘ └────────────┘ └────────────┘ └────────────┘
│ │ │ │
▼ ▼ ▼ ▼
Adding Work in Finishing All issues
issues progress last items resolved
Milestone States
| State | Indicators |
|---|---|
| Planning | Issues being added, 0% complete |
| Active | Work in progress, 1-80% complete |
| Closing | Final stretch, 80-99% complete |
| Closed | 100% complete, milestone closed |
Updating Milestones
Update Description/Due Date
# Update due date
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]"
Close a Milestone
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:
# Phase 1: Foundation
gh api repos/$GITHUB_OWNER/$GITHUB_REPO/milestones -X POST \
-f title="[Initiative] Phase 1: Foundation" \
-f description="Infrastructure and setup for [Initiative Name]"
# Phase 2: Core Features
gh api repos/$GITHUB_OWNER/$GITHUB_REPO/milestones -X POST \
-f title="[Initiative] Phase 2: Core Features" \
-f description="Primary feature implementation"
# Phase 3: Polish & Launch
gh api repos/$GITHUB_OWNER/$GITHUB_REPO/milestones -X POST \
-f title="[Initiative] Phase 3: Polish & Launch" \
-f description="Final testing, polish, and release"
Release Milestones
For version-based releases:
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"
Quarterly Milestones
For quarterly planning:
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"
Handling Slippage
When issues won't make a milestone:
Option 1: Move to Next Milestone
gh issue edit [ISSUE_NUMBER] --milestone "[NEXT_MILESTONE]"
Option 2: Extend Milestone
gh api repos/$GITHUB_OWNER/$GITHUB_REPO/milestones/[NUMBER] \
-X PATCH \
-f due_on="[NEW_DATE]"
Option 3: Reduce Scope
Move non-critical issues out:
# Remove from milestone (set to no milestone)
gh issue edit [ISSUE_NUMBER] --milestone ""
Document Slippage
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]"
Milestone Reports
Weekly Status Report
## Milestone Status Report - [DATE]
### [MILESTONE 1]
- **Progress:** 12/20 (60%)
- **Due:** [DATE]
- **Status:** 🟢 On Track
- **Blockers:** None
### [MILESTONE 2]
- **Progress:** 3/15 (20%)
- **Due:** [DATE]
- **Status:** 🟡 At Risk
- **Blockers:** Waiting on #123
### [MILESTONE 3]
- **Progress:** 0/10 (0%)
- **Due:** [DATE]
- **Status:** ⚪ Not Started
- **Blockers:** Depends on Milestone 2
Generate Report Script
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"'
Memory Integration
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]"
]
}])
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