moko-platform/docs/workflows/dev-branch-tracking.md

<!--
Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>

SPDX-License-Identifier: GPL-3.0-or-later

# FILE INFORMATION
DEFGROUP: MokoStandards.Documentation
INGROUP: MokoStandards.Workflows
REPO: https://git.mokoconsulting.tech/MokoConsulting/MokoStandards-API
PATH: /docs/workflows/dev-branch-tracking.md
VERSION: 04.06.00
BRIEF: Dev branch tracking and issue coordination system documentation
-->

[![MokoStandards](https://img.shields.io/badge/MokoStandards-04.06.00-orange)](https://git.mokoconsulting.tech/MokoConsulting/MokoStandards)

# Dev Branch Tracking and Issue Coordination

**Status**: Active | **Version**: 02.00.00 | **Effective**: 2026-04-07

## Overview

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**:
1. Creates tracking issue with branch details and version info
2. Creates 7 sub-issues:
   - Feature development
   - Unit testing
   - Integration testing
   - Code review
   - Documentation updates
   - Changelog updates
   - Version management
3. Assigns issues to `copilot` and `jmiller`
4. 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**:
1. Creates tracking issue with RC branch details and version
2. 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
3. Creates a **draft GitHub Release** for the major version (`vXX`)
4. Assigns issues to `copilot` and `jmiller`
5. 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):
1. Finds the tracking issue for the base branch
2. Adds PR as checklist item in the "📝 Pull Requests" section
3. Comments on the tracking issue with PR details

**When PR Merges** (to dev/rc branch):
1. Updates checklist item from `[ ]` to `[x]` in tracking issue
2. Comments on tracking issue confirming merge

**When PR Merges to Main**:
1. Closes the tracking issue for the merged branch
2. Adds comprehensive closing comment with merge details

**When Branch Deleted**:
1. Finds and closes the tracking issue
2. 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:

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

### RC Branch Sub-Issues (5)

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

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

## Workflow Sequence

### Dev Branch Lifecycle (Manual Trigger)

```mermaid
sequenceDiagram
    participant Dev as Developer
    participant GH as GitHub 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)

```mermaid
sequenceDiagram
    participant Dev as Developer
    participant RCBranch as rc/XX.YY.ZZ
    participant GH as GitHub 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:

```bash
# 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:

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

### Working with Tracking Issues

**As a Developer:**

```bash
# 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:**

1. Review PR targeting dev branch
2. Check tracking issue for context
3. Verify checklist items as they're completed
4. 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](../policy/copilot-pre-merge-checklist.md):

- 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**:
1. Branch name doesn't match pattern (`dev/*`, `alpha/*`, `beta/*`, or `rc/*`)
2. Tracking issue doesn't exist
3. Tracking issue missing `dev-branch` label

**Solution**:
1. Verify branch name starts with `dev/`, `alpha/`, `beta/`, or `rc/`
2. Check if tracking issue exists with label `dev-branch`
3. Manually create issue using template if needed

### PR Not Added to Tracking Issue

**Symptom**: PR opened but not appearing in tracking issue

**Causes**:
1. Tracking issue has non-standard format
2. Missing "📝 Pull Requests" section
3. Workflow error (check Actions tab)

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

### Tracking Issue Not Closing

**Symptom**: Dev branch merged to main but issue still open

**Causes**:
1. Branch name mismatch in issue body
2. Workflow not triggered on merge
3. Issue manually closed earlier

**Solution**:
1. Verify issue body contains correct branch name in backticks
2. Check Actions tab for workflow run on merge
3. Manually close issue if workflow didn't run

## Best Practices

### For Maintainers

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

### For Contributors

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

### For CI/CD

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

## Related Documentation

- [Copilot Pre-Merge Checklist Policy](../policy/copilot-pre-merge-checklist.md)
- [Auto-Create Dev Branch Workflow](../../.gitea/workflows/auto-create-dev-branch.yml)
- [Enterprise Issue Manager Workflow](../../.gitea/workflows/enterprise-issue-manager.yml)
- [Dev Branch Tracking Template](../../.github/ISSUE_TEMPLATE/dev-branch-tracking.md)
- [Workflow Architecture](./workflow-architecture.md)
- [Contributing Guide](../../CONTRIBUTING.md)

## 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 |