Skip to content

milestones.md

Latest commit

 

History

History
325 lines (248 loc) · 7.59 KB

milestones.md

File metadata and controls

325 lines (248 loc) · 7.59 KB

Milestones

← Back to Index | ← Comments | Next: Design Elements →

Manage project milestones for tracking major deliverables and releases.

Table of Contents

  1. list_milestones
  2. get_milestone
  3. create_milestone
  4. update_milestone
  5. delete_milestone
  6. close_milestone / reopen_milestone

list_milestones

List project milestones.

Parameters:

  • projectId (number, optional): Project ID
  • offset (number, optional): Pagination offset
  • limit (number, optional): Max items (default: 50, max: 200)

Returns: { items, total, offset, limit, hasMore }

Example:

const milestones = await callTool('list_milestones', {
  projectId: 230954
});

// Filter to active milestones
const active = milestones.items.filter(m => !m.closingDate);

// Sort by due date
const sorted = active.sort((a, b) =>
  new Date(a.dueDate) - new Date(b.dueDate)
);

get_milestone

Get milestone details.

Parameters:

  • projectId (number, optional): Project ID
  • milestoneId (number, required): Milestone ID

Returns: Milestone object

Response Fields:

  • milestoneId: Milestone identifier
  • name: Milestone name
  • description: Description
  • dueDate: Target completion date (ISO 8601)
  • closingDate: When milestone was closed (null if active)
  • workItemCount: Number of assigned work items
  • completedWorkItemCount: Completed items count

Example:

const milestone = await callTool('get_milestone', {
  projectId: 230954,
  milestoneId: 456
});

const completion = (milestone.completedWorkItemCount / milestone.workItemCount) * 100;
console.log(`${milestone.name}: ${completion.toFixed(1)}% complete`);

create_milestone

Create a new milestone.

Parameters:

  • projectId (number, optional): Project ID
  • name (string, required): Milestone name
  • description (string, optional): Description
  • dueDate (string, optional): Due date (ISO 8601 format)

Returns: Created milestone object

Example:

const milestone = await callTool('create_milestone', {
  projectId: 230954,
  name: 'v1.0 Release',
  description: 'Initial public release with core features',
  dueDate: '2026-03-31T23:59:59Z'
});

Naming Conventions:

  • Version numbers: v1.0, v2.5.1
  • Features: Multiplayer Launch, Content Update #1
  • Phases: Alpha, Beta, Release Candidate

update_milestone

Update milestone properties.

Parameters:

  • projectId (number, optional): Project ID
  • milestoneId (number, required): Milestone ID
  • name (string, optional): New name
  • description (string, optional): New description
  • dueDate (string, optional): New due date

Returns: Updated milestone object

Example:

// Extend milestone deadline
await callTool('update_milestone', {
  projectId: 230954,
  milestoneId: 456,
  dueDate: '2026-04-15T23:59:59Z',
  description: 'Extended for additional polish and testing'
});

delete_milestone

Delete a milestone.

Parameters:

  • projectId (number, optional): Project ID
  • milestoneId (number, required): Milestone ID

Returns: { success: boolean }

Warning:

  • Permanently deletes the milestone
  • Work items assigned to this milestone are not deleted
  • Milestone assignment is removed from work items
  • Cannot be undone

Recommended Alternative: Use close_milestone to archive.

close_milestone / reopen_milestone

Close or reopen a milestone.

Parameters:

  • projectId (number, optional): Project ID
  • milestoneId (number, required): Milestone ID

Returns: { success: boolean }

Example:

// Archive completed milestone
await callTool('close_milestone', {
  projectId: 230954,
  milestoneId: 456
});

// Reopen for post-release fixes
await callTool('reopen_milestone', {
  projectId: 230954,
  milestoneId: 456
});

Behavior:

  • Closed milestones: Hidden from active milestone lists
  • Work items: Can still be assigned to closed milestones
  • Metrics: Remain queryable

Common Patterns

Create Release Milestones

// Create milestones for quarterly releases
const quarters = [
  { name: 'Q1 2026 Release', date: '2026-03-31' },
  { name: 'Q2 2026 Release', date: '2026-06-30' },
  { name: 'Q3 2026 Release', date: '2026-09-30' },
  { name: 'Q4 2026 Release', date: '2026-12-31' }
];

for (const q of quarters) {
  await callTool('create_milestone', {
    projectId: 230954,
    name: q.name,
    dueDate: `${q.date}T23:59:59Z`
  });
}

Assign Work Items to Milestone

// Assign all "high priority" items to upcoming milestone
const highPriority = await callTool('search_work_items', {
  projectId: 230954,
  importanceLevels: ['urgent', 'high'],
  isCompleted: false
});

await callTool('update_work_items', {
  projectId: 230954,
  items: highPriority.items.map(item => ({
    workItemId: item.workItemId,
    milestoneId: 456  // "v1.0 Release"
  }))
});

Milestone Progress Report

const milestones = await callTool('list_milestones', {
  projectId: 230954
});

console.log('Milestone Progress Report\n');

for (const m of milestones.items.filter(m => !m.closingDate)) {
  const completion = (m.completedWorkItemCount / m.workItemCount) * 100;
  const daysUntil = Math.ceil(
    (new Date(m.dueDate) - new Date()) / (1000 * 60 * 60 * 24)
  );

  console.log(`${m.name}:`);
  console.log(`  Progress: ${completion.toFixed(1)}%`);
  console.log(`  Tasks: ${m.completedWorkItemCount}/${m.workItemCount}`);
  console.log(`  Due: ${daysUntil} days`);
  console.log('');
}

Feature-Based Milestones

// Create milestone for specific feature
const featureMilestone = await callTool('create_milestone', {
  projectId: 230954,
  name: 'Multiplayer System',
  description: `## Scope
- Lobby system
- Matchmaking
- In-game networking
- Leaderboards

## Success Criteria
- 10 players per match
- <50ms latency
- Cross-platform support`
});

// Create and assign feature tasks
const tasks = await callTool('create_work_items', {
  projectId: 230954,
  items: [
    { title: 'Design multiplayer architecture', categoryId: 'design', milestoneId: featureMilestone.milestoneId },
    { title: 'Implement lobby system', categoryId: 'programming', milestoneId: featureMilestone.milestoneId },
    { title: 'Build matchmaking service', categoryId: 'programming', milestoneId: featureMilestone.milestoneId }
  ]
});

Best Practices

Milestone Planning

Do:

  • Create milestones for major releases/features
  • Set realistic due dates with buffer time
  • Use descriptive names with version numbers
  • Include scope in description

Don't:

  • Create too many milestones (keep <10 active)
  • Set arbitrary dates without planning
  • Mix different types (features + releases)

Milestone vs Board

Use Milestones for:

  • Long-term goals (months)
  • Releases and versions
  • Cross-sprint features
  • External deadlines

Use Boards for:

  • Short iterations (weeks)
  • Sprint planning
  • Team velocity tracking
  • Time-boxed work

Combine Both:

// Milestone: "v1.0 Release" (3 months)
//   └─ Board: "Sprint 1" (2 weeks) → subset of v1.0 tasks
//   └─ Board: "Sprint 2" (2 weeks) → more v1.0 tasks
//   └─ Board: "Sprint 3" (2 weeks) → final v1.0 tasks

See Also: