This document describes the dev/rc branch tracking and issue coordination system. Dev branches use manual workflow_dispatch to create tracking issues, while RC branches auto-create tracking issues and a draft GitHub Release on branch creation.

Branch Issue Summary

Branch Type	Issue Creation	Sub-Issues	Draft Release?
`dev/**`	Manual (workflow_dispatch)	7 sub-issues	No
`alpha/**`	Manual (workflow_dispatch)	7 sub-issues	No
`beta/**`	Manual (workflow_dispatch)	7 sub-issues	No
`rc/**`	Automatic (on branch creation)	5 sub-issues	Yes

Note: Alpha and beta branches are optional stages. Dev can go directly to rc when internal/external testing stages are not needed.

System Components

The tracking system consists of three main components:

1. Dev Branch Issue Creation (Manual)

Trigger: Manual workflow_dispatch only

Purpose: Creates a tracking issue + 7 sub-issues for a dev branch when manually triggered.

Why manual? Dev branches are exploratory and may be short-lived. Not every dev branch needs full tracking overhead.

Actions:

Creates tracking issue with branch details and version info
Creates 7 sub-issues:
- Feature development
- Unit testing
- Integration testing
- Code review
- Documentation updates
- Changelog updates
- Version management
Assigns issues to copilot and jmiller
Adds labels: automation, version-management, dev-branch

2. RC Branch Issue Creation (Automatic)

Trigger: Automatic on rc/** branch creation

Purpose: Auto-creates a tracking issue + 5 sub-issues + draft GitHub Release when an RC branch is pushed.

Actions:

Creates tracking issue with RC branch details and version
Creates 5 sub-issues:
- Comprehensive testing (functional, integration, performance)
- Bug fixes and regression testing
- Documentation and changelog finalization
- Release notes preparation
- Final verification and sign-off
Creates a draft GitHub Release for the major version (vXX)
Assigns issues to copilot and jmiller
Adds labels: automation, version-management, rc-branch

The draft release is later published by auto-release.yml when the RC merges to main.

2. Enterprise Issue Manager Workflow

File: .gitea/workflows/enterprise-issue-manager.yml

Purpose: Coordinates pull requests with dev branch tracking issues throughout the PR lifecycle.

Triggers:

Pull request events: opened, closed, reopened, ready_for_review
Branch deletion events
Manual workflow dispatch

Actions for PRs:

When PR Opens (targeting dev/rc branch):

Finds the tracking issue for the base branch
Adds PR as checklist item in the "📝 Pull Requests" section
Comments on the tracking issue with PR details

When PR Merges (to dev/rc branch):

Updates checklist item from [ ] to [x] in tracking issue
Comments on tracking issue confirming merge

When PR Merges to Main:

Closes the tracking issue for the merged branch
Adds comprehensive closing comment with merge details

When Branch Deleted:

Finds and closes the tracking issue
Adds comment explaining branch deletion

3. Dev Branch Tracking Issue Template

File: .github/ISSUE_TEMPLATE/dev-branch-tracking.md

Purpose: Manual creation of tracking issues for dev branches not created by the workflow.

Use Cases:

Manually created dev branches
Retroactively adding tracking for existing branches
Custom branch naming outside standard pattern

Contents:

Placeholder fields for branch name and version
Complete 10-section launch checklist
PR tracking section
Labels and assignees pre-configured

Sub-Issue Checklists

Dev Branch Sub-Issues (7)

When manually triggered via workflow_dispatch, the following sub-issues are created:

Feature Development — implement planned features for this version
Unit Testing — write and pass unit tests for new code
Integration Testing — verify integration with other components
Code Review — address all review comments, re-review significant changes
Documentation Updates — update README, user guides, examples
Changelog Updates — document all changes grouped by type (Added, Changed, Fixed, etc.)
Version Management — ensure version consistency across all files, update headers

RC Branch Sub-Issues (5)

Automatically created when an rc/** branch is pushed:

Comprehensive Testing — functional, integration, and performance testing
Bug Fixes and Regression — fix issues found in testing, verify no regressions
Documentation and Changelog — finalize docs and CHANGELOG.md
Release Notes Preparation — draft release notes, document breaking changes, migration guide
Final Verification and Sign-off — all PRs merged, no blocking issues, ready for main

Workflow Sequence

Dev Branch Lifecycle (Manual Trigger)

sequenceDiagram
    participant Dev as Developer
    participant GH as Gitea Actions
    participant Issue as Tracking Issue
    participant EIM as Enterprise Issue Manager
    participant DevBranch as dev/XX.YY

    Dev->>DevBranch: Create dev branch manually
    Dev->>GH: Run workflow_dispatch
    GH->>Issue: Create tracking issue + 7 sub-issues

    Dev->>DevBranch: Open PR #123
    DevBranch->>EIM: Trigger on PR opened
    EIM->>Issue: Add PR #123 to checklist

    Dev->>DevBranch: Merge PR #123
    DevBranch->>EIM: Trigger on PR closed
    EIM->>Issue: Mark PR #123 as [x]

RC Branch Lifecycle (Automatic)

sequenceDiagram
    participant Dev as Developer
    participant RCBranch as rc/XX.YY.ZZ
    participant GH as Gitea Actions
    participant Issue as Tracking Issue
    participant Release as Draft Release
    participant Main as main

    Dev->>RCBranch: Push rc/XX.YY.ZZ branch
    RCBranch->>GH: Auto-trigger on branch creation
    GH->>Issue: Create tracking issue + 5 sub-issues
    GH->>Release: Create draft GitHub Release (vXX)

    Dev->>RCBranch: Test and fix bugs
    Dev->>Main: Merge RC to main via PR
    Main->>GH: auto-release.yml publishes draft release
    GH->>Issue: Close tracking issue

Usage Examples

Automatic Workflow

No action required. When a PR is merged to main:

# Developer merges PR to main via GitHub UI
# Workflow automatically:
# 1. Creates dev/04.01 branch
# 2. Creates tracking issue #456
# 3. Assigns to copilot and jmiller

Manual Issue Creation

For manually created dev branches:

Navigate to repository Issues
Click "New Issue"
Select "Dev Branch Tracking" template
Fill in the placeholders:
- Replace XX.YY.ZZ with actual version
- Update branch name in details
- Add creation date
Submit issue

Working with Tracking Issues

As a Developer:

# 1. Check out the dev branch
git fetch origin
git checkout dev/04.01

# 2. Find the tracking issue (labeled 'dev-branch')
# 3. Create PR targeting the dev branch
gh pr create --base dev/04.01 --title "Add feature X"

# 4. PR automatically added to tracking issue
# 5. When ready to merge to main, complete checklist in tracking issue
# 6. Create final PR to main
gh pr create --base main --head dev/04.01 --title "Release 04.00.04"

As a Reviewer:

Review PR targeting dev branch
Check tracking issue for context
Verify checklist items as they're completed
Before approving final PR to main, verify all checklist items are complete

Integration with Other Workflows

Pre-Merge Checklist Policy

The launch checklist aligns with the Copilot Pre-Merge Checklist Policy:

Same 8 core sections
Additional 2 sections specific to branch merges
Reference link included in every tracking issue

Standards Compliance Workflow

The "Standards Compliance" checklist section integrates with:

.gitea/workflows/standards-compliance.yml
File header validation
Formatting standards checks

Security Workflows

The "Security Scanning" checklist section integrates with:

CodeQL security analysis
Dependency review workflow
Secret scanning

Configuration

Assignees

Default assignees for tracking issues:

copilot (GitHub Copilot agent)
jmiller (organization owner — GitHub assignees must be a user account, not an org)

To change assignees:

Auto-created issues: Edit .gitea/workflows/auto-create-dev-branch.yml line 289
Manual template: Edit .github/ISSUE_TEMPLATE/dev-branch-tracking.md line 6

Labels

Default labels for tracking issues:

automation - Automated process
version-management - Version tracking
dev-branch - Development branch marker

To change labels:

Auto-created issues: Edit .gitea/workflows/auto-create-dev-branch.yml line 288
Manual template: Edit .github/ISSUE_TEMPLATE/dev-branch-tracking.md line 5

Branch Patterns

The system tracks branches matching:

dev/* - Development branches
alpha/* - Alpha testing branches (optional stage)
beta/* - Beta testing branches (optional stage)
rc/* - Release candidate branches

To modify patterns, edit .gitea/workflows/enterprise-issue-manager.yml line 143.

Troubleshooting

Tracking Issue Not Found

Symptom: PR opened but not linked to tracking issue

Causes:

Branch name doesn't match pattern (dev/*, alpha/*, beta/*, or rc/*)
Tracking issue doesn't exist
Tracking issue missing dev-branch label

Solution:

Verify branch name starts with dev/, alpha/, beta/, or rc/
Check if tracking issue exists with label dev-branch
Manually create issue using template if needed

PR Not Added to Tracking Issue

Symptom: PR opened but not appearing in tracking issue

Causes:

Tracking issue has non-standard format
Missing "📝 Pull Requests" section
Workflow error (check Actions tab)

Solution:

Check workflow run in Actions tab for errors
Manually add PR to tracking issue: - [ ] #123 - PR Title (@author)
Ensure tracking issue has "📝 Pull Requests" section

Tracking Issue Not Closing

Symptom: Dev branch merged to main but issue still open

Causes:

Branch name mismatch in issue body
Workflow not triggered on merge
Issue manually closed earlier

Solution:

Verify issue body contains correct branch name in backticks
Check Actions tab for workflow run on merge
Manually close issue if workflow didn't run

Best Practices

For Maintainers

Monitor tracking issues - Review open dev-branch issues regularly
Complete checklists - Don't skip checklist items before merging to main
Update assignees - Add relevant team members to tracking issues
Link related issues - Reference related issues in tracking issue comments

For Contributors

Check tracking issue - Review before creating PR to dev branch
Follow checklist - Use checklist as guide for PR requirements
Update status - Comment on tracking issue with progress updates
Test thoroughly - Verify all checklist items apply to your changes

For CI/CD

Status checks - Reference tracking issue in PR descriptions
Automated tests - Run tests mentioned in checklist automatically
Quality gates - Block merge if checklist items incomplete
Documentation - Auto-generate release notes from tracking issues

Changelog

Version	Date	Changes
02.00.00	2026-04-07	Rewrite: dev branches use manual workflow_dispatch, RC branches auto-create issues + draft release. Updated sub-issue counts (7 for dev, 5 for RC)
01.00.00	2026-02-06	Initial documentation of dev branch tracking system

Repo: moko-platform · moko-platform wiki

Field	Value
Minimum Version	04.07.00
Platform	all
Applies To	All repositories

Revision	Date	Author	Description
1.0	2026-05-08	Moko Consulting	Initial version

Dev Branch Tracking and Issue Coordination

Overview

Branch Issue Summary

System Components

1. Dev Branch Issue Creation (Manual)

2. RC Branch Issue Creation (Automatic)

2. Enterprise Issue Manager Workflow

3. Dev Branch Tracking Issue Template

Sub-Issue Checklists

Dev Branch Sub-Issues (7)

RC Branch Sub-Issues (5)

Workflow Sequence

Dev Branch Lifecycle (Manual Trigger)

RC Branch Lifecycle (Automatic)

Usage Examples

Automatic Workflow

Manual Issue Creation

Working with Tracking Issues

Integration with Other Workflows

Pre-Merge Checklist Policy

Standards Compliance Workflow

Security Workflows

Configuration

Assignees

Labels

Branch Patterns

Troubleshooting

Tracking Issue Not Found

PR Not Added to Tracking Issue

Tracking Issue Not Closing

Best Practices

For Maintainers

For Contributors

For CI/CD

Related Documentation

Changelog