Milestones are a project management feature that allows you to group issues and pull requests (PRs) around a specific goal or timeframe. Milestones are often used to track progress toward project deadlines, manage sprints, or align with release cycles.
By linking pull requests to milestones, you can make sure that development work aligns with broader project objectives, enabling better tracking of progress and resource allocation. In this guide, we’ll explore how to link pull requests to GitHub milestones and track them efficiently by incorporating tools like Graphite’s PR inbox for enhanced organization.
Steps to link pull requests to milestones in GitHub
1. Create or select a milestone
Before linking a pull request to a milestone, check that the milestone exists in your GitHub repository.
- Navigate to the Issues tab in your repository.
- Click on Milestones from the menu on the left.
- Select an existing milestone or create a new one by clicking New milestone.
- Set the title, due date, and description to define the milestone's scope.
2. Assign a milestone to a pull request
Once a milestone exists, you can assign it to a pull request directly.
- Open the pull request you want to link.
- In the right-hand sidebar under the Development section, click on Milestone.
- Choose the relevant milestone from the dropdown list.
This links the pull request to the milestone, making it easier to track its contribution to the milestone's progress.
3. Use labels and custom filters for better tracking
To complement milestones, you can apply labels to pull requests to further categorize them by priority, type, or team responsibility. For example, use labels like frontend
, backend
, or high-priority
to sort PRs linked to a milestone.
Enhancing workflow with the Graphite PR inbox
While GitHub provides native milestone tracking, tools like Graphite can further enhance your PR management strategies. Graphite’s PR inbox serves as an organizational hub for managing pull requests across multiple repositories, with customizable sections that streamline your view of PRs linked to milestones.
Setting up the Graphite PR inbox
- Default repositories: Ensure your relevant repositories are added to Graphite’s PR inbox. On the free tier, you can select up to three default repositories, and up to 30 on Team or Enterprise tiers.
- Create custom sections: Use the "Add new section" feature to filter PRs based on milestone association. For example, create a section showing all PRs linked to a specific milestone by configuring filters like
milestone:<milestone-name>
. - Rearrange sections for priority: Drag and drop sections in your inbox to keep milestone-related PRs easily accessible.
Benefits of using Graphite for PR management
- Centralized views: Group PRs by milestone across repositories, even if they aren’t in your default repository list.
- Search and filters: Use the Graphite search bar with milestone-related keywords to locate specific PRs quickly.
- Collaboration: Share section configurations with teammates to ensure consistent tracking of milestones.
Example workflow: Linking PRs to project milestones
Here’s a step-by-step example of linking pull requests to milestones and using Graphite for tracking:
Define a milestone: In GitHub, create a milestone called
Feature-Launch
. Assign a due date of December 15th.Link PRs to the milestone: Assign all relevant pull requests to
Feature-Launch
using the milestone dropdown in GitHub.Track in Graphite: Set up a custom section in Graphite’s PR inbox with the filter
milestone:Feature-Launch
. This will group all PRs associated with the milestone.Collaborate efficiently: Share the custom section with teammates via Graphite to ensure everyone is aligned on milestone progress.
Monitor milestone completion: Use Graphite’s "Needs your review" section to prioritize milestone-related PRs requiring attention, ensuring the team meets the deadline.
Linking pull requests to milestones in GitHub encourages alignment between code contributions and project goals. By leveraging Graphite’s PR inbox, you can add even more organizational tools that simplify milestone tracking and collaboration.