Sprint Progress View
Relevant source files
The following files were used as context for generating this wiki page:
The Sprint Progress View is a core functional component of the Refined GitHub Projects extension designed to provide real-time visibility into the health and velocity of the current iteration. It serves as a centralized dashboard within the GitHub Projects UI, aggregating data from GraphQL mutations and background processing to display issue completion rates, point velocity, and scope changes. Sources: src/components/sprint/sprint-progress-view.tsx, README.md:95-97
This module integrates deeply with the GitHub Projects V2 metadata, allowing users to track progress based on custom fields like "Story Points" and "Status" without leaving the project table view. It enables critical sprint management workflows, including automated "End Sprint" rollovers where incomplete items are migrated to subsequent iterations. Sources: src/components/sprint/sprint-modal.tsx, src/entries/background/handlers/sprint-handlers.ts:315-320
Architecture and Data Flow
The Sprint Progress View operates on a client-server model between the Content Script (UI) and the Background Service Worker (Data Processing). The UI triggers requests via typed messages, and the background worker performs sequential GraphQL queries to calculate metrics. Sources: src/entries/background/handlers/sprint-handlers.ts:1-15, src/components/sprint/sprint-progress-view.tsx:105-115
Data Retrieval Sequence
When the view is initialized, it requests sprint status and progress data. The background handler fetches project items, filters them by the active iteration ID, and computes completion percentages.
The system utilizes a 1-second delay between mutation calls to remain rate-limit safe, ensuring the Personal Access Token (PAT) is not throttled during large-scale updates. Sources: src/entries/background/handlers/sprint-handlers.ts:405, CONTRIBUTING.md:14-17
Core Components
The Sprint Progress View is composed of several specialized React components that handle specific parts of the dashboard. Sources: src/components/sprint/sprint-progress-view.tsx:45-120
Sprint Progress Dashboard
The main SprintProgressView component manages the lifecycle of the progress data, including loading states and error handling. Sources: src/components/sprint/sprint-progress-view.tsx:85-100
| Component | Description | Key Props / Logic |
|---|---|---|
MetricBar | Visual progress bar for Issues or Points. | Calculates percentage via pct(done, total). |
SprintProgressView | The container component for metrics and scope changes. | Uses useEffect to trigger getSprintProgress message. |
SprintGroupHeaderWidget | A small widget injected into the project header. | Provides quick access to "End Sprint" or settings. |
SprintPanel | The modal overlay containing settings and rollover views. | Manages PanelState (loading, active, etc.). |
Sources: src/components/sprint/sprint-progress-view.tsx:48-65, src/components/sprint/sprint-table-widget.tsx:25-45, src/components/sprint/sprint-modal.tsx:645-660
Metric Calculation Logic
Progress metrics are calculated based on the SprintSettings defined by the user for a specific project. Sources: src/entries/background/handlers/sprint-handlers.ts:165-180
Issue and Points Completion
The background worker iterates through all items assigned to the current iteration. An item is considered "Done" if its status field matches the doneOptionId (for single-select fields) or doneOptionName (for text fields). Sources: src/entries/background/handlers/sprint-handlers.ts:182-200
- Total Issues: Count of all items where the Iteration field matches the active ID.
- Done Issues: Items matching the "Done" condition.
- Story Points: Sum of the numeric values in the designated
pointsFieldId. - Scope Change: Items where
createdAtis greater than thesprintSnapshotAtorsprintStartDate.
Sprint Rollover (End Sprint)
The "End Sprint" feature is a destructive operation that migrates work. It identifies "Not Done" items and moves them to the next iteration. Sources: src/entries/background/handlers/sprint-handlers.ts:275-290
Rollover Process
- Item Discovery: All items in the current iteration are fetched.
- Exclusion Filtering: Items matching
excludeConditions(e.g., specific labels or types) are kept in the current sprint even if not done. Sources: src/entries/background/handlers/sprint-handlers.ts:325-345 - Sequential Migration: Incomplete items are updated to the
nextIterationIdone-by-one with a 1000ms sleep interval. Sources: src/entries/background/handlers/sprint-handlers.ts:385-400
Configuration and Persistence
Sprint settings are stored per project ID in the browser's storage via allSprintSettingsStorage. Sources: src/entries/background/handlers/sprint-handlers.ts:25-30
| Field | Type | Description |
|---|---|---|
sprintFieldId | string | The ID of the Iteration field in GitHub. |
doneFieldId | string | The field used to track completion (Status/Text). |
pointsFieldId | string | Optional numeric field for weight/effort. |
excludeConditions | Array | Rules for items that should not migrate. |
sprintSnapshotAt | ISO String | Timestamp for measuring scope creep. |
Sources: src/components/sprint/sprint-modal.tsx:135-160, src/entries/background/handlers/sprint-handlers.ts:90-100
Summary
The Sprint Progress View provides a vital layer of project management on top of GitHub Projects V2. By leveraging background processing and sequential GraphQL mutations, it maintains data accuracy while respecting GitHub's API limits. The system's ability to track scope changes and automate the migration of incomplete work significantly reduces manual overhead during sprint transitions. Sources: README.md:95-102, src/components/sprint/sprint-progress-view.tsx:215-225