Split into sub-issues

An issue filed where the work was reported — a tracking repository, or a customer’s request — is often not where the work happens. Split into sub-issues creates the pieces in the repositories that will actually carry them, and links each one back as a GitHub sub-issue.

Splitting an issue

1. Open the issue and select Split into sub-issues, under the body or from the command palette.
2. For each piece, fill in its Repository, Title and, optionally, Body. A child can be in a different repository from the parent — that is the point. Select Add a sub-issue for another row.
3. Select Create sub-issues.

Each child’s body ends with a line naming the parent, so the relationship reads on GitHub as well as in Pealboard. One to twenty children per split, because each one is a write to GitHub.

A closed issue cannot be split. GitHub does not accept a sub-issue under a closed issue; reopen it first.

When GitHub creates a child but will not link it

GitHub allows a hundred sub-issues under one parent and eight levels of nesting. A child past either limit is still created — it exists in GitHub — but is marked Not linked, with GitHub’s own sentence saying why. It is not attached to the parent, but it is not lost: find it and link it by hand on GitHub, or leave it as an ordinary issue.

If a split is refused partway through, the children it had already created stay created. The refusal names them, with links, so you can remove them or leave them out before splitting again — nothing here writes a second copy of an issue that already exists.

Parent and sub-issues, on the issue itself

A sub-issue shows Sub-issue of repository#number title above its own title, linking to the parent. If the parent is in a repository this workspace does not mirror, the line says so instead of linking anywhere: turn that repository’s sync on under Settings → GitHub to open it.

A parent shows a Sub-issues section under its body, with a progress count — 3 of 7 completed — and every child Pealboard has cached. Only sub-issues in a repository this workspace mirrors appear there. GitHub’s own count, shown beside it, may be higher when a child lives in a repository Pealboard does not sync; that child exists on GitHub and is simply not one Pealboard has ever seen.

What splitting does not do

• Move the parent issue. The parent stays where it was created; splitting adds children, it does not relocate anything. Moving an issue between repositories is not something GitHub’s API supports at all — see Create and edit an issue.
• Close the parent. Completing every child does not change the parent’s state. Close it yourself when the work it named is done.
• Keep children in sync with each other. Each child is an ordinary issue once created: editing one does not change its siblings or the parent.