Multi Repo Workflow

Multi-Repo Workflow

The QQQ ecosystem spans 25+ repositories. This guide covers how to coordinate changes, manage issues, and release across multiple repos.

Quick Links

• Home
• GitHub Project #12
• Repository Catalog
• Compatibility Matrix

Repository Structure

Core Dependencies

qqq-core (foundation)
├── qqq-frontend-core (TypeScript client)
│   └── qqq-frontend-material-dashboard (React dashboard)
├── qbit-bom (parent POM)
│   └── All QBits
└── qqq-orb (CI/CD)

Key Repositories

Repo	Purpose	Default Branch
qqq	Core framework	develop
qqq-frontend-core	TypeScript client	develop
qqq-frontend-material-dashboard	React dashboard	develop
qbit-bom	QBit parent POM	main
qqq-orb	CircleCI orb	develop
meta-manager	Ecosystem management	main

GitHub Project #12

All QQQ ecosystem work is tracked in GitHub Project #12.

Columns

Column	Purpose
Backlog	Triaged issues awaiting work
In Progress	Actively being worked on
In Review	PR submitted, awaiting review
Done	Merged to develop
Released	Included in a release

Labels

Standard labels across all repos:

Label	Purpose
bug	Bug reports
enhancement	Feature requests
documentation	Documentation updates
breaking-change	Breaking API changes
multi-repo	Spans multiple repositories
priority:p1-p4	Priority level
severity:critical-low	Bug severity

Cross-Repo Changes

When Changes Span Repos

1. Create Issue - Open issue in the primary affected repo
2. Label Multi-Repo - Add multi-repo label
3. Link in Project - Add to Project #12
4. Create Related Issues - Open linked issues in each affected repo
5. Coordinate PRs - Submit PRs in dependency order

Dependency Order

When changes touch multiple repos, merge in this order:

1. qqq (core) - Foundation changes first
2. qqq-frontend-core - TypeScript client updates
3. qqq-frontend-material-dashboard - Dashboard updates
4. qbit-bom - Update parent POM versions
5. QBits - Update individual QBits
6. qqq-orb - CI/CD updates

Example: API Change

1. qqq: Add new API endpoint
   └── PR #123 merged to develop

2. qqq-frontend-core: Add TypeScript types
   └── PR #45 (depends on qqq #123)
   └── Merged after qqq release

3. qqq-frontend-material-dashboard: Add UI
   └── PR #67 (depends on frontend-core #45)
   └── Merged after frontend-core release

Issue Coordination

Creating Multi-Repo Issues

Use this template for the primary issue:

## Summary
Description of the cross-repo change

## Affected Repositories
- [ ] qqq - Core changes
- [ ] qqq-frontend-core - TypeScript updates
- [ ] qqq-frontend-material-dashboard - UI changes

## Related Issues
- qqq-frontend-core#45
- qqq-frontend-material-dashboard#67

## Implementation Order
1. qqq: [description]
2. frontend-core: [description]
3. dashboard: [description]

## Compatibility Notes
- Requires qqq >= X.Y.Z
- Breaking change: [yes/no]

Linking Issues

Link related issues across repos:

• Use Fixes QRun-IO/repo#123 in PR descriptions
• Add cross-references in issue comments
• Ensure all related issues are in Project #12

Release Coordination

Version Alignment

• Frontend versions track core versions (qqq 0.27.x = frontend 0.27.x)
• QBits specify minimum QQQ version compatibility
• See Compatibility Matrix for details

Coordinated Release

When releasing breaking changes:

1. Freeze qqq - Complete all core changes
2. Release qqq - Tag and publish
3. Update Dependencies - Update frontend/QBit POMs
4. Release Dependents - Tag and publish each
5. Update Compatibility - Update meta-manager docs

Release Checklist

• All related PRs merged
• All CI checks passing
• Version numbers aligned
• Compatibility matrix updated
• CHANGELOG entries added
• GitHub Releases created

Branch Coordination

Branch Naming

Consistent branch names across repos:

# Feature spanning repos
feature/add-streaming-api  # Same name in all repos

# Bug fix spanning repos
fix/issue-123-null-pointer  # Reference primary issue

Sync Points

Keep branches in sync:

1. Daily - Pull upstream changes to feature branches
2. Before PR - Rebase on target branch
3. After Merge - Delete feature branches in all repos

Tooling

meta-manager

The meta-manager repo coordinates:

• Compatibility Matrix - Version compatibility tracking
• Repository Catalog - List of all repos
• Automation Scripts - Cross-repo operations

qqq-orb

The qqq-orb provides CI/CD:

• Consistent build/test pipelines
• Automated GitHub Releases
• Maven Central publishing

Common Scenarios

Scenario: New Entity Type

1. Add entity support to qqq core
2. Add TypeScript types to qqq-frontend-core
3. Add UI components to qqq-frontend-material-dashboard
4. Update QBits that use entities

Scenario: Breaking API Change

1. Follow Deprecation Policy
2. Add deprecation warnings in minor release
3. Coordinate removal across all repos
4. Release as major version

Scenario: New QBit

1. Create from template
2. Register in qbit-bom
3. Add to meta-manager compatibility docs
4. Publish to Maven Central

See Also

• Release Flow - Release process
• Branching and Versioning - Branch strategy
• Compatibility Matrix - Version compatibility
• QBit Development - Creating QBits