Skip to content

ADR-005: Repository Migration Strategy

Status

Approved - 2025-11-13

Context

The SyRF monorepo was initially developed in a test repository (camaradesuk/syrf-test) to validate the monorepo structure, CI/CD workflows, and GitOps deployment before committing to production. Now that the monorepo is stable and functional, we need to migrate it to the production repository.

Current State

Three repositories exist:

  1. camaradesuk/syrf-web - Original Angular frontend repository
  2. Contains 470+ GitHub issues
  3. Contains 47 open pull requests
  4. Contains GitHub Discussions
  5. Contains ZenHub workspace configuration

  6. Team familiar with this repository name

  7. camaradesuk/syrf-test - Monorepo test repository

  8. Contains complete monorepo code (all services + libraries)
  9. Contains validated CI/CD workflows
  10. Contains GitVersion configuration
  11. Contains 3 branches (main, backup-before-web-remerge, migration)

  12. Contains monorepo version tags (api-v*, pm-v*, web-v*, etc.)

  13. Multiple archived polyrepos - Original service repositories

  14. syrf-api, syrf-projectmanagement, syrf-lib-* (all archived)

Problem Statement

We need to consolidate the monorepo into a single production repository while:

  • Preserving valuable GitHub metadata (issues, PRs, discussions)
  • Maintaining ZenHub workspace continuity
  • Minimizing disruption to team workflows
  • Preserving git history traceability

Original Plan

Initially planned repository name: camaradesuk/syrf-monorepo

Why this is suboptimal:

  • Creates yet another repository (4th total)
  • Fragments GitHub metadata across repositories
  • Loses connection to existing issues and PRs
  • Requires ZenHub workspace migration/reconfiguration
  • Confusing for users (which repo to use?)

Decision

Migrate the monorepo to camaradesuk/syrf by force-pushing to the existing syrf-web repository and renaming it.

Migration Strategy

  1. Create backup: Mirror syrf-web to camaradesuk/syrf-web-legacy (all branches, tags, refs)
  2. Force push monorepo: Push all branches and tags from syrf-test to syrf-web
  3. Rename repository: Rename syrf-web to syrf via GitHub settings
  4. Update references: Update documentation and remote URLs

Why This Approach

Preserves GitHub metadata (most critical):

  • All 470+ issues remain in place with original IDs
  • All 47 PRs remain in place (may need rebasing)
  • All GitHub Discussions preserved
  • All repository settings preserved (secrets, webhooks, collaborators)
  • All GitHub Actions workflows and run history preserved

ZenHub continuity:

  • Repository rename is transparent to ZenHub (same internal repo ID)
  • Workspace continues functioning without reconfiguration
  • All ZenHub metadata preserved (epics, estimates, dependencies)

Git history traceability:

  • syrf-web's main branch history already merged into monorepo (via git mv)
  • Force push preserves this ancestry relationship
  • File history traceable from old paths to new paths
  • All commits remain accessible via git log

GitHub automatic redirects:

  • Old URLs (camaradesuk/syrf-web) redirect to new URLs (camaradesuk/syrf)
  • External links continue working
  • Minimal impact on bookmarks and external references

Consequences

Positive

  1. Single source of truth: One repository for all code and metadata
  2. Metadata preservation: No loss of issues, PRs, or discussions
  3. Zero ZenHub disruption: Workspace continues functioning without changes
  4. Git history preserved: Full traceability via git log and git mv
  5. Automatic redirects: Old URLs continue working via GitHub redirects
  6. Clean repository name: syrf (not syrf-monorepo) aligns with project name

Negative

  1. Open PRs require rebasing: PRs targeting old file paths need manual updates
  2. Example: /src/app/component.ts → src/services/web/src/app/component.ts

  3. Only affects 3 recent PRs (44 older PRs are stale and can be closed)

  4. Team must update local clones: One-time action to update remote URLs

git remote set-url origin https://github.com/camaradesuk/syrf.git
  1. Force push is destructive: Original syrf-web code replaced on main branch
  2. Mitigation: Complete backup created in syrf-web-legacy

  3. Mitigation: Original code still accessible via backup repo and git history

  4. Documentation updates required: 28 files need updating

  5. syrf-monorepo → syrf (naming consistency)
  6. camaradesuk/syrf-test → camaradesuk/syrf (URL updates)

Neutral

  1. Branch coexistence: 96 total branches after migration (3 monorepo + 93 original)
  2. No naming conflicts detected

  3. Original feature branches preserved for reference

  4. Tag coexistence: 700+ tags after migration (monorepo + original)

  5. No naming conflicts (monorepo uses prefixes: api-v*, pm-v*, web-v*)
  6. Original syrf-web tags preserved (unprefixed: v3.*, v4.*)

Alternatives Considered

Alternative 1: Create New Repository (syrf-monorepo)

Description: Create brand new repository camaradesuk/syrf-monorepo and start fresh.

Pros:

  • Clean slate, no force push needed
  • No risk of breaking existing PRs

Cons:

  • ❌ Loses all GitHub metadata (470+ issues, 47 PRs, discussions)
  • ❌ Requires ZenHub migration (workspace reconfiguration, metadata may not transfer)
  • ❌ Fragments history (issues in old repo, code in new repo)
  • ❌ Confusing for users ("Which repo do I use?")
  • ❌ External links broken (no automatic redirects)

Verdict: Rejected - Metadata loss is unacceptable.

Alternative 2: Rename syrf-test to syrf

Description: Simply rename the test repository to the production name.

Pros:

  • Simplest technical approach
  • No force push required

Cons:

  • ❌ Loses all GitHub metadata from syrf-web (470+ issues, 47 PRs, discussions)
  • ❌ Loses ZenHub workspace (configured on syrf-web, not syrf-test)
  • ❌ No automatic redirects (syrf-test → syrf, but syrf-web remains orphaned)
  • ❌ Team confusion ("Where did all our issues go?")

Verdict: Rejected - Unacceptable metadata loss.

Alternative 3: GitHub Repository Transfer

Description: Use GitHub's repository transfer feature to move syrf-test's code while preserving syrf-web's metadata.

Pros:

  • Native GitHub feature
  • Designed for repository migrations

Cons:

  • ❌ Not applicable: Transfer moves entire repository, not just code
  • ❌ Cannot merge repositories: Transfer doesn't combine metadata from two repos
  • ❌ Still requires force push: To combine repos, force push is necessary

Verdict: Rejected - GitHub transfers don't solve the metadata consolidation problem.

Implementation Plan

See Repository Migration Guide for detailed step-by-step instructions.

High-level phases:

  1. Pre-migration: Review and handle 47 open PRs (merge/close/keep)
  2. Create backup: Mirror syrf-web to syrf-web-legacy (safety net)
  3. Force push: Push monorepo from syrf-test to syrf-web (preserves metadata)
  4. Rename: Rename syrf-web to syrf (GitHub handles redirects)
  5. Update references: Update 28 documentation files
  6. Validate: Verify ZenHub, CI/CD, branches, tags, issues, PRs

Estimated time: 3 hours

Validation

Success criteria:

  • ✅ Repository accessible at https://github.com/camaradesuk/syrf
  • ✅ All 470+ issues accessible with original IDs
  • ✅ All 47 PRs accessible (may need rebasing)
  • ✅ ZenHub workspace functional (same workspace ID)
  • ✅ All branches present (96 total: 3 monorepo + 93 original)
  • ✅ All tags present (700+: monorepo + original)
  • ✅ Git history traceable (syrf-web commits visible in git log)
  • ✅ CI/CD runs successfully on new repository
  • ✅ Old URLs redirect to new repository

Rollback Plan

If critical issues arise:

Option 1: Rename back to syrf-web

  • Preserves all metadata
  • Simple one-step revert

Option 2: Restore from backup

  • Force push from syrf-web-legacy to restore original state
  • Requires re-archiving or deleting the monorepo attempt

Option 3: Continue using syrf-test

  • Unarchive syrf-test
  • Document decision to keep separate repositories

References

Decision Record

Date: 2025-11-13

Decision makers: Chris (Product Owner), Claude Code (Technical Advisor)

Approved by: Chris

Implementation target: ASAP (with detailed documentation for reference)

Notes

Why Not "syrf-monorepo"?

The name "syrf-monorepo" was initially planned to clearly distinguish the monorepo from individual service repositories. However:

  1. All old service repos are archived - No ambiguity remains
  2. "monorepo" is an implementation detail - Users don't need to know the internal structure
  3. Simpler is better - syrf aligns with project branding
  4. Precedent: Most organizations use simple names (e.g., facebook/react, not facebook/react-monorepo)

Branch and Tag Conflicts

Analysis performed (2025-11-13):

  • Branches: 3 syrf-test branches, 93 syrf-web branches → No conflicts
  • Tags: Monorepo uses prefixes (api-v*, pm-v*, web-v*), syrf-web uses unprefixed (v*) → No conflicts

Open PRs Impact

47 open PRs as of 2025-11-13:

  • 3 recent PRs (2025-10 to 2025-11) - Require manual review and decision
  • 44 older PRs (2021-2024) - Candidates for closure (stale)

Force push impact on PRs:

  • PRs remain open and functional
  • Base branch (main) code changes, so PRs may need rebasing
  • File path changes (due to git mv) require manual conflict resolution
  • Recommendation: Merge or close PRs before migration for cleaner migration

ZenHub Behavior

Repository renames in ZenHub:

  • ZenHub uses internal repository ID (not name)
  • Renaming a repository doesn't break ZenHub workspace
  • Workspace automatically shows new repository name
  • All ZenHub metadata preserved (epics, estimates, dependencies, pipelines)

Verified behavior: GitHub repository renames are transparent to ZenHub.

Change Log

Date Change Author
2025-11-13 Initial ADR creation Claude Code