Skip to content

BRANCHING.md

Latest commit

 

History

History
252 lines (178 loc) · 7.24 KB

BRANCHING.md

File metadata and controls

252 lines (178 loc) · 7.24 KB
Raw

Branching Strategy: v1.5 vs v2.5 Development

Overview

This project runs two parallel development tracks for 3-6 months:

  • main (v1.5 Stable) — Production-ready tool for live trading. Your buddy owns this.
  • v2-architecture (v2.5 Development) — Next-generation learning system. You own this.

Both exist in the same repository. They diverge significantly after initial split, but can pull from each other strategically.

Branch Rules

main (v1.5 — Your Buddy's Track)

Purpose: Stable, polished, tradeable version.

Allowed changes:

  • Bug fixes and demo hardening
  • Performance improvements (within existing architecture)
  • UI/UX polish
  • Documentation
  • Minor config refinements
  • Test improvements

NOT allowed:

  • New architectural patterns (actors, flywheel, regime detection, social traces)
  • Refactoring the pipeline (it's frozen)
  • Adding new major subsystems

Release cycle: Manual, when your buddy decides it's ready. Tag as v1.5.0, v1.5.1, etc.

Your involvement: Code review on major PRs. Accept pull requests from v2-architecture for critical bug fixes.

v2-architecture (v2.5 — Your Development Track)

Purpose: Experimental, learning-enabled future system. Follows the 5-upgrade blueprint.

Planned sprints:

  • Sprint 4: Regime Detection + Homeostasis
  • Sprint 5: Flywheel + Active Inference
  • Sprint 6: Stigmergic Social Traces
  • Sprint 7: Temporal Binding + Full Dashboard

Allowed:

  • All architectural changes from blueprint
  • Refactoring into actor model
  • New subsystems (inference, homeostasis, social, temporal)
  • Breaking changes (if necessary for the architecture)
  • Experimental features

Release cycle: Internal iteration. When ready (after Sprint 7?), plan v2.0.0 release + merge to main.

Your buddy's involvement: Can cherry-pick specific bug fixes if needed, but v2 is experimental territory.

Workflow

For Your Buddy (main track)

# Work on v1.5 fixes
git checkout main
git pull origin main
git checkout -b fix/demo-hardening
# ... make changes ...
git push origin fix/demo-hardening
# Create PR to main, merge when ready

For You (v2 track)

# Work on v2 features
git checkout v2-architecture
git pull origin v2-architecture
git checkout -b feature/regime-detection
# ... make changes ...
git push origin feature/regime-detection
# Create PR to v2-architecture, merge when ready

Keeping v2-architecture Fresh (Pull Critical Fixes from main)

Every 2-4 weeks, pull critical bug fixes from main into v2-architecture:

git checkout v2-architecture
git pull origin v2-architecture
git pull origin main  # Merges main into v2-architecture
# If conflicts: resolve, commit
git push origin v2-architecture

This keeps v2 benefiting from v1.5 bug fixes without pulling in v1's entire evolution.

When v2 is Ready (Merge Back to main)

After Sprint 7, when v2 is stable:

git checkout main
git pull origin main
git merge --no-ff v2-architecture -m "Merge v2-architecture: regime detection, homeostasis, flywheel, social traces, temporal binding"
git push origin main
git tag v2.0.0
git push origin v2.0.0

Your buddy's 3-6 months of v1.5 improvements will still be on main. Merge conflicts might need resolution, but the structure supports it.

File Structure Impact

Both branches share these files (stable):

config/methods.yaml
config/symbols.yaml
src/confluence_engine/models.py
src/confluence_engine/methods/
frontend/
tests/

v2-architecture DIVERGES here (new subsystems):

src/confluence_engine/
  ├── actors/          (NEW)
  ├── inference/       (NEW)
  ├── homeostasis/     (NEW)
  ├── social/          (NEW)
  ├── regime/          (NEW)
  ├── flywheel/        (NEW)
  ├── temporal/        (NEW)
  └── engine/          (REFACTORED - supervision tree instead of batch pipeline)

v1.5 main keeps engine as-is:

src/confluence_engine/engine/
  └── pipeline.py      (unchanged from v1.5)

Conflict Resolution Strategy

Scenario 1: Bug fix on v1.5 that v2 needs

Example: Critical cache bug in src/confluence_engine/data/cache.py

  1. Your buddy fixes it on main, merges to main
  2. You cherry-pick the specific commit to v2-architecture: 
    git checkout v2-architecture
git cherry-pick <commit-hash-from-main>
  3. If conflicts, resolve manually
  4. Continue with v2 development

Scenario 2: v2 adds a new subsystem, main doesn't have it

No conflict. The directories are new. main never pulls v2 until final merge.

Scenario 3: Final merge of v2 to main (after Sprint 7)

This is the big one. You'll merge the entire v2-architecture branch to main:

git checkout main
git merge v2-architecture

Expected conflicts:

  • src/confluence_engine/engine/pipeline.py — v2 refactored into actors/supervision tree, but main might have bug fixes
  • config/methods.yaml — both might have method additions
  • tests/ — both added tests in different places
  • API routes might diverge

Resolution: Manual, deliberate merge. Preserve main's bug fixes. Integrate v2's new architecture.

Monitoring & Communication

Weekly Sync with Your Buddy

  • What bugs fixed on v1.5?
  • Any critical issues blocking demo?
  • What are the top 3 things to polish next?

When to Pull v1.5 Fixes into v2

If your buddy fixes:

  • Cache bugs → cherry-pick to v2
  • Performance issues → cherry-pick to v2
  • API response bugs → cherry-pick to v2
  • UI polish → ignore (v2 might refactor UI anyway)

FAQ

Q: Will v2-architecture get out of sync with main?

A: Yes, and that's OK. You'll be implementing fundamentally different architecture. After 3-6 months, v2 might be very different. That's the point.

Q: What if I find a bug on v2-architecture that affects main?

A: Fix it on v2-architecture first, then cherry-pick or backport the fix to a new PR to main for your buddy to review.

Q: Can my buddy use v2 features before they're merged to main?

A: No. v2-architecture is experimental. Your buddy stays on main (v1.5) for stability.

Q: What if 6 months passes and v2 isn't ready?

A: v1.5 (main) keeps working as-is. v2-architecture continues in development. You pivot based on what matters most.

Q: Should we use feature flags to ship v2 gradually to main?

A: Not initially. Keep them separate for 3-6 months. After v2 is stable and tested, then merge. Feature flags add complexity and coupling right now.

Summary Table

Aspect main (v1.5) v2-architecture (v2.5)
Owner Your buddy You
Stability High — production Experimental
Architecture Batch pipeline Actor model + learning
Target Users Live traders Research, next version
Merge frequency Stable, tagged releases Internal only
Pull from each other Only critical bugs All improvements on occasion
Final merge After Sprint 7 → main becomes v2.0 Plan for v2.0 release

Next Steps

  1. Create v2-architecture branch (you do this now)
  2. Share this BRANCHING.md with your buddy
  3. Agree on "what counts as critical enough to cherry-pick"
  4. Weekly sync to stay aligned
  5. After 3-6 months: evaluate v2 readiness for merge to main