Context & History of GitHub Sub‑issues

GitHub issues have long served as the core of collaborative development, allowing teams to track bugs, feature requests, and tasks. Over the years, enhancements such as labels, milestones, and task lists have made issue tracking more powerful. As projects grew in size, the need for a structured way to break large tasks into smaller, trackable pieces became evident. The sub‑issues feature was introduced to fill this gap, giving users the ability to create nested issue lists that reflect real‑world project hierarchies while keeping the familiar GitHub experience.

Implementation & Best Practices for Sub‑issues

To adopt sub‑issues effectively, start by mapping your major deliverables to parent issues, then identify logical child tasks that can be represented as sub‑issues. Update your data model to store parent‑child relationships, expose the new structure via GraphQL, and adjust your UI components to render nested lists. Follow the roadmap below before adding deeper technical details.

Roadmap for Adding Sub‑issues

1. Define hierarchy List top‑level goals and outline the required subtasks.
2. Update the database Add a table that records parent and child issue IDs, and a summary table for roll‑up progress.
3. Expose via GraphQL Create queries and mutations that allow clients to fetch and modify the hierarchy.
4. Adjust UI components Reuse existing list‑view components and add controls for creating, editing, and reordering sub‑issues.
5. Test accessibility Work with design teams to ensure keyboard navigation and screen‑reader support.
6. Dogfood internally Apply the new workflow to internal projects to uncover edge cases before public release.

Data Modeling

The sub‑issues table stores a simple parent_id and child_id pair, making it easy to query relationships in MySQL. A companion progress table aggregates completion percentages, allowing the parent issue to display overall status without expensive recursive queries. This design also supports enterprise deployments where data residency rules apply.

API Exposure

GraphQL endpoints were extended to include parentIssue and subIssues fields. Clients can now request nested structures in a single request, reducing round‑trips and improving performance. For a deeper look at API design patterns, see the Web Interoperability 2024 guide, which discusses efficient data fetching strategies.

User Experience Design

Controls for adding sub‑issues appear inline with the main issue body, preserving the workflow users expect. Metadata such as issue number and repository name is displayed when sub‑issues reside in different repositories, helping teams track cross‑repo dependencies. The design principles align with accessibility standards, as detailed in the Page Visibility API article, ensuring that dynamic UI updates are announced correctly to assistive technologies.

Key takeaways Use a clear parent‑child map, leverage GraphQL for efficient data access, and validate the experience with internal testing before releasing to users.