Parent and Sub-Issues

Use sub-issues to break down larger "parent" issues into smaller pieces of work.

Overview

Consider creating sub-issues when a set of work is too large to be a single issue but too small to be a project. Sub-issues also ideal for splitting up work shared across teammates. When you add a sub-issue to another issue, the other issue becomes its "parent".

We treat sub-issues and their parent issues as representing discrete units of work. A sub-issue is related to its parent, but they do not share properties and do not sum up or aggregate properties. A sub-issue has its own own estimate count, assignee, labels, team, etc that is unrelated to the parent issue and vice versa.

If you use parent issues to summarize work but the sub-issues represent the actionable work needed, you can configure estimates in team settings to allow for zero estimates, then assign a zero point value to parent issues. However, you'll still need to close the parent issue when its sub-issues have been completed. We're considering adding additional automations in this area -- if this is something you'd find useful, please let us know at support@linear.app.

Basics

Create sub-issues

Create sub-issues directly by opening the parent issue and then clicking the + Add sub-issues button below the issue description. This will launch the sub-issue editor. You can also use the shortcut Command Shift O to open the editor.

You can also create sub-issues in the issue creation modal (C) by pressing Command Shift O to open the editor or under the ... menu and "Add sub-issue".

When you save a sub-issue, it will automatically launch the editor to create a new one. If you want to create a new one with the same values (labels/assignee etc.) you can press Command Shift Enter or Shift+click the save button.
Press Esc to exit the sub-issue editor and continue updating the parent issue.

You can turn a comment under an issue into a sub-issue by hovering over a comment and clicking the ... menu then "new sub-issue from comment".
Selecting a comment's text and pressing Command Shift O will also create a sub-issue.

If you have a list (bulleted, numbered or checklist) you can highlight the checklist and hit Command Shift O to convert to sub-issues or choose the "Create sub-issues(s) from selection" item in the formatting toolbar.

You can add a template using the templates icon when creating a sub-issue or using the command menu under "Create new sub-issue from template" when viewing the Parent.

Copy properties

Sub-issues created in the editor automatically copy issue properties from the parent issue such as the project and cycle as long as those are set before you create the sub-issue.

Team, labels and assignees are not copied over. You can't create sub-issues while editing the parent issue, but the option will come up once you press save.

You can duplicate a parent and its sub-issues from the Parent's ...menu under "Duplicate" and hit the toggle "Include sub-issues".

Turn issues into sub-issues

Turn an existing issue(s) into sub-issues of another issue by selecting one or multiple issues and then taking the action to set the parent issue. This action is accessible from the command menu.

Turn issues into parent issues

To make an existing issue a parent issue of another issue, hover over a sub-issue and take the action "Set Parent" in the contextual menu, command menu or ∙∙∙ menu.

Turn sub-issues into issues

You can turn a sub-issue into a regular issue again using the CMD/CTRLK menu option Remove parent.

Turn issues into projects

Sometimes an issue grows so large it's more appropriate to turn it into a project instead. To do so, hover over the Parent's ∙∙∙ menu and choose "Convert to project." The project will inherit its details from the original parent issue, and former sub-issues will become standard issues in the project

Update sub-issues

Update a sub-issue to edit it just like you would any other issue. You can make changes to the sub-issue from a list or board view or open it to edit.

To make changes to a sub-issue while viewing the parent issue, hover over the issue in the sub-issue list and then use a keyboard shortcut or right-click to open a contextual menu to update any issue field. Some issue fields will show up by default on the issue, such as assignee and team, and you can click to update those.

We also support multi-selecting sub-issues to update them from the parent issue by selecting the checkbox beside each issue, or using X to select using your keyboard.

You can move sub-issues to a new team without moving the parent issue through the command line, or with the shortcut Cmd/Ctrl Shift M.

Filter sub-issues

You can usually set the view to show or hide sub-issues in Display Options. You can also use Filters to show only top-level (parent) issues, issues with sub-issues, or only sub-issues. If you use these filters frequently, consider creating a custom view.

You can also hide completed sub-issues by default under the … menu and toggling "Always hide completed sub-issues".

You can also sort your sub-issues under an issue from the … menu and "Order by" though this only updates it for the current user, not globally.

Navigate between issues

Navigate between a parent issue and its sub-issues by using the menu pictured.