Sprint Ending & Management
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
Sprint Ending & Management is a core feature of the Refined GitHub Projects extension designed to automate the lifecycle of iterations within GitHub Projects V2. It provides a centralized interface for tracking progress, configuring sprint-specific metadata (such as "Done" conditions and "Story Points"), and executing the "End Sprint" transition.
The system automates the movement of incomplete items to a subsequent iteration while keeping completed items in the current sprint. It utilizes a background worker and a sequential task queue to interact with the GitHub GraphQL API, ensuring rate-limit compliance during bulk migrations.
Sources: README.md:55-58, src/entries/background/handlers/sprint-handlers.ts:251-255
System Architecture
The Sprint Management system follows a decoupled architecture where the UI components communicate with a background service worker via a typed messaging system.
Component Overview
- SprintModal & SprintProgressView: React-based UI components that display metrics, allow configuration changes, and trigger the end-sprint workflow. Sources: src/components/sprint/sprint-modal.tsx:949-960, src/components/sprint/sprint-progress-view.tsx:88-97
- SprintGroupHeaderWidget: An inline UI element injected into the GitHub Projects table that provides quick access to sprint status and actions. Sources: src/components/sprint/sprint-table-widget.tsx:21-27
- Background Handlers: Logic located in the service worker that performs GraphQL queries, manages state in browser storage, and processes the migration queue. Sources: src/entries/background/handlers/sprint-handlers.ts:21-25
Data Flow for Sprint Ending
The following sequence diagram illustrates the process of ending a sprint and migrating items.
Core Features & Logic
Sprint Configuration
Users must define specific project fields to enable sprint tracking. This configuration is stored in the extension's local storage and used to interpret item states.
| Configuration Field | Description | Type |
|---|---|---|
sprintFieldId | The ID of the Iteration field used for sprints. | String |
doneFieldId | The field (Single Select or Text) used to determine if an item is finished. | String |
doneOptionId | The specific option ID (for Single Select) that marks an item as "Done". | String |
pointsFieldId | Optional field (Number) used to aggregate story points/velocity. | String |
excludeConditions | Rules to prevent specific items from migrating even if incomplete. | Array |
Sources: src/components/sprint/sprint-modal.tsx:161-182, src/entries/background/handlers/sprint-handlers.ts:29-30
Progress Calculation
The getSprintProgress handler calculates metrics by paginating through all items assigned to the active iteration. It compares item field values against the configured doneFieldId and notStartedOptionId.
End-Sprint Migration Logic
When a sprint ends, the system identifies "Incomplete" items. An item is considered incomplete if:
- Its
doneFieldvalue does not match thedoneOptionId(ordoneOptionValue). - It does not match any user-defined
excludeConditions(e.g., items marked as "Won't Do" can be excluded from moving to the next sprint).
The migration is handled by the processQueue utility, which ensures a 1-second delay between every mutation to prevent GitHub PAT abuse 403 errors.
Sources: src/entries/background/handlers/sprint-handlers.ts:333-353, CONTRIBUTING.md:12-16
Technical Implementation Details
API Operations
The system relies on specific GraphQL queries to manage iteration data.
GET_PROJECT_FIELDS: Used to retrieve the available iterations and field configurations (includingcompletedIterations). Sources: src/lib/graphql/queries.ts:49-106GET_SPRINT_PROGRESS_ITEMS: Fetches item content, creation dates, and field values specifically for progress visualization. Sources: src/lib/graphql/queries.ts:153-189UPDATE_PROJECT_FIELD: Mutation used to change the iteration ID of an item. Sources: src/entries/background/handlers/sprint-handlers.ts:386-391
Concurrency & Performance
To prevent race conditions, the extension implements concurrency locks for destructive operations.
isSprintEndFull()/acquireSprintEnd(): Ensures only one end-sprint migration runs at a time for the user. Sources: src/entries/background/handlers/sprint-handlers.ts:254-259- Cache Management: Sprint progress data is cached using
sprintProgressCachewith a TTL (Time To Live) to reduce redundant API calls during UI re-renders. Sources: src/entries/background/handlers/sprint-handlers.ts:139-148
Summary
The Sprint Ending & Management module provides an automated bridge between iterations in GitHub Projects V2. By combining a configuration-driven logic engine with a safe, sequential background migration worker, it allows teams to "close" work cycles with a single click while maintaining accurate velocity and scope change metrics.