1

workflows-sub-issue-management.-

Jonathan Miller edited this page 2026-05-08 02:34:41 +00:00

Table of Contents

• Sub-Issue Management Guide
• Overview
• When to Use Sub-Issues
• Creating Sub-Issues
• Method 1: Using the Issue Template (Manual)
• Method 2: Using the Automated Workflow
• Sub-Issue Best Practices
• Naming Convention
• Description Guidelines
• Acceptance Criteria
• Labels
• Linking to Parent Issues
• Tracking Progress
• In the Sub-Issue
• In the Parent Issue
• Example: Creating Sub-Issues for Issue #193
• Configuration
• Closing Sub-Issues
• Automation
• Related Resources
• Support

← Home

Sub-Issue Management Guide

Overview

Sub-issues (also called sub-tasks) are a way to break down complex parent issues into smaller, manageable pieces of work. This guide explains how to create and manage sub-issues in the moko-platform repository.

When to Use Sub-Issues

Use sub-issues when:

• A parent issue is too large to tackle in one PR
• Multiple people need to work on different aspects of an issue
• You want to track progress on specific components of a larger task
• An issue requires multiple sequential steps that should be tracked separately

Creating Sub-Issues

Method 1: Using the Issue Template (Manual)

1. Go to the New Issue page
2. Select the "Sub-Task" template
3. Fill in the required fields:
   • Parent Issue: The issue number this sub-task belongs to (e.g., #193)
   • Task Title: A brief, descriptive title
   • Task Description: Detailed description of the work
   • Task Type: Investigation, Bug Fix, Feature Implementation, etc.
   • Priority: Low, Medium, High, or Critical
4. Optionally add:
   • Acceptance criteria (checklist format)
   • Dependencies on other issues
   • Additional notes or context
5. Submit the issue

Method 2: Using the Automated Workflow

For programmatic sub-issue creation:

1. Go to Actions → Create Sub-Issue
2. Click "Run workflow"
3. Fill in the workflow inputs:
   • Parent issue: The parent issue number (e.g., 193)
   • Title: Sub-issue title
   • Description: Detailed description
   • Task type: Choose from dropdown
   • Priority: Choose from dropdown
   • Assignees: Comma-separated GitHub usernames (optional)
   • Labels: Additional labels, comma-separated (optional)
4. Click "Run workflow"

The workflow will:

• Validate the parent issue exists
• Create the sub-issue with appropriate labels
• Link it to the parent issue
• Add a comment to the parent issue
• Validate all assignees before assignment

Sub-Issue Best Practices

Naming Convention

Use clear, action-oriented titles:

• ✅ Good: [Task] Investigate GH_TOKEN permissions
• ✅ Good: [Task] Update documentation for bulk sync process
• ❌ Bad: Token stuff
• ❌ Bad: Fix #193

Description Guidelines

Include:

• Clear description of what needs to be done
• Why this work is necessary
• Any relevant context or background
• Links to related issues, PRs, or documentation

Acceptance Criteria

Use checkboxes to define when the sub-task is complete:

- [ ] All token permissions verified
- [ ] Documentation updated with findings
- [ ] Changes tested in staging environment

Labels

Sub-issues automatically receive the sub-task label. Add additional labels as appropriate:

• Priority labels: priority/low, priority/medium, priority/high, priority/critical
• Type labels: bug, enhancement, documentation
• Component labels: automation, infrastructure, security

Linking to Parent Issues

Always reference the parent issue in the sub-issue description:

**Parent Issue**: #193 - Bulk Repository Sync Failed

The automated workflow does this automatically.

Tracking Progress

In the Sub-Issue

Use the progress checklist in the sub-issue body to track completion:

### Progress Tracking
- [x] Task started
- [x] Implementation complete
- [x] Tests passing
- [ ] Documentation updated
- [ ] Code review complete
- [ ] Ready to close

In the Parent Issue

Add a section to the parent issue to track all sub-issues:

## Sub-Issues

- [ ] #194 - Investigate GH_TOKEN permissions
- [x] #195 - Update bulk sync documentation
- [ ] #196 - Add retry logic to sync script

Update this as sub-issues are completed.

Example: Creating Sub-Issues for Issue #193

For issue #193 (Bulk Repository Sync Failed), you might create these sub-issues:

1. Investigation: [Task] Investigate GH_TOKEN permissions and scopes
2. Bug Fix: [Task] Add retry logic for transient network failures
3. Documentation: [Task] Document troubleshooting steps for sync failures
4. Testing: [Task] Test bulk sync with different repository configurations

Each sub-issue would:

• Reference #193 as the parent
• Have a clear, specific scope
• Include acceptance criteria
• Be assigned to the appropriate team member

Configuration

Sub-issue behavior is controlled by .github/issue-management-config.yml:

# Sub-Issue Management
sub_issues:
  enabled: true
  
  # Automatically create sub-issues for
  auto_create_for:
    - prs: true
    - tasks: false
  
  # Sub-issue naming
  naming:
    pr_prefix: "[PR]"
    task_prefix: "[Task]"
  
  # Progress tracking
  progress:
    update_parent: true
    show_percentage: true
    show_checklist: true

Closing Sub-Issues

Close a sub-issue when:

• All acceptance criteria are met
• The work has been reviewed and approved
• Any related PRs have been merged
• The parent issue acknowledges completion

Add a closing comment explaining what was accomplished:

Closing this sub-issue. All acceptance criteria met:
- Token permissions verified and documented
- Updated documentation with findings
- Changes tested and working

See PR #XXX for implementation details.

Automation

The Create Sub-Issue workflow provides automation for:

• Validation: Ensures parent issue exists before creating sub-issue
• Linking: Automatically links sub-issue to parent with comments
• Assignee validation: Verifies assignees are valid GitHub users
• Label management: Applies appropriate labels based on inputs
• Summary generation: Provides clear summary of created sub-issue

Related Resources

• Issue Management Configuration
• Sub-Task Template
• Create Sub-Issue Workflow
• GitHub Issues Documentation

Support

If you encounter issues with sub-issue creation:

1. Check that the parent issue number is correct
2. Verify you have permission to create issues
3. Ensure assignees are valid GitHub usernames
4. Review the workflow run logs for error details
5. Open a bug report if the issue persists