Docs/Version Control/Merging

Version Control

Merging

Combine branches to bring experimental changes into your main taste profile. Merging consolidates constraints, exemplars, and comparisons from multiple branches.

Understanding Merges

Merging combines the changes from one branch (the source) into another branch (the target). Unlike code merges, taste profile merges combine training data rather than replacing it.

Before merge:
main ─────●─────●─────●──────────────────> (50 labels, 100 comparisons)
           │
           └─── experiment ─────●─────●──> (20 labels, 40 comparisons)

After merge:
main ─────●─────●─────●─────●────────────> (70 labels, 140 comparisons)
           │              ╱
           └─── experiment ─────●─────●──> (unchanged)

Additive Merge

New exemplars and comparisons from the source branch are added to the target. Duplicates are automatically deduplicated.

Constraint Handling

Conflicting constraints (same question, different answer) require manual resolution.

Merge Workflow

1
Ensure Both Branches Are Committed
Commit any uncommitted changes on both the source and target branches before merging.
2
Review Changes
Compare the source branch's changes to understand what will be merged.
3
Resolve Conflicts (If Any)
Handle any constraint conflicts by choosing which answer to keep.
4
Execute Merge
The merge creates a new commit on the target branch with combined data.
5
Verify Results
Test the merged profile to ensure the combined taste reflects your intent.

Merging via Dashboard

1Navigate to your profile's Merge page
2Select the source branch (the one with changes to merge)
3Select the target branch (usually main)
4Review the merge preview showing what will change
5Resolve any conflicts if prompted
6Click Confirm Merge

Merging via API

To merge programmatically, combine the snapshots and create a new version on the target branch:

Merge Process (Pseudocode)

// 1. Get both branch snapshots
const mainSnapshot = profile.versions.find(v => v.id === mainBranch.headVersionId).snapshot;
const expSnapshot = profile.versions.find(v => v.id === expBranch.headVersionId).snapshot;

// 2. Combine data (deduplicate by ID)
const mergedSnapshot = {
  constraints: mergeByKey(mainSnapshot.constraints, expSnapshot.constraints, 'id'),
  exemplars: mergeByKey(mainSnapshot.exemplars, expSnapshot.exemplars, 'id'),
  comparisons: mergeByKey(mainSnapshot.comparisons, expSnapshot.comparisons, 'id'),
  latentScores: { ...mainSnapshot.latentScores, ...expSnapshot.latentScores },
};

// 3. Recompute derived data
mergedSnapshot.embeddingCentroid = computeCentroid(mergedSnapshot.exemplars);
mergedSnapshot.promptSummary = generateSummary(mergedSnapshot);

// 4. Create merge commit
const mergeVersion = {
  id: generateId(),
  branchId: 'main',
  parentVersionId: mainBranch.headVersionId,
  mergedFromVersionId: expBranch.headVersionId,
  message: 'Merge experiment branch into main',
  snapshot: mergedSnapshot,
  createdAt: new Date().toISOString(),
};

// 5. Update profile via API
await updateProfile(profileId, {
  profileData: {
    versions: [...profile.profileData.versions, mergeVersion],
    branches: profile.profileData.branches.map(b =>
      b.id === 'main' ? { ...b, headVersionId: mergeVersion.id } : b
    ),
  },
  effectiveSnapshot: mergedSnapshot,
});

Conflict Resolution

Conflicts occur when both branches have modified the same data in incompatible ways. The most common conflict type is constraint conflicts.

Constraint Conflict Example

When the same question has different answers on different branches:

Question: "What mood should images evoke?"

Main branch: "Calm and peaceful"

Experiment branch: "Energetic and vibrant"

Resolution Strategies

Keep Target (Main)

Preserve the target branch's answer, discarding the source branch's answer for this constraint.

Keep Source (Experiment)

Use the source branch's answer, overwriting the target branch's answer.

Keep Both (Create New Constraint)

Rephrase as two separate constraints if both answers are valuable.

Best Practices

Merge Often

Regular merges keep branches from diverging too far, reducing conflicts.

Test Before Merging to Main

Use the evaluation API to verify the experimental branch produces good scores before merging into production.

Document Merge Decisions

Write clear merge commit messages explaining why changes were merged and how conflicts were resolved.

Delete Merged Branches

Clean up experiment branches after successful merges to keep your profile structure manageable.