Merge Requests & Conflicts

Learn how to use merge requests for collaborative review and resolve conflicts in KiCad files.

Merge Requests

Merge requests (MRs) let you propose changes and get feedback from your team before merging.

Creating a Merge Request

  1. Push your changes to a branch (not the main branch)
  2. Go to your repository on Paplix
  3. Click Merge Requests → New Merge Request
  4. Select your source branch (your changes)
  5. Select the target branch (usually main)
  6. Add a title and description
  7. Click Create Merge Request

Reviewing Changes

In a merge request, you can:

  • View File Changes - See which files were modified
  • Visual Diff - For KiCad files, see component-level changes
  • Comment - Leave feedback on specific changes
  • Approve/Request Changes - Signal your review status

Visual Diff for KiCad Files

Unlike traditional text diffs, Paplix shows visual changes:

  • Added Components - Highlighted in green
  • Removed Components - Highlighted in red
  • Modified Components - Highlighted in yellow
  • Moved Components - Shown with position indicators

This makes it easy to understand what changed in your schematic or PCB.

Merging

Once approved, merge the request:

  1. Click Merge on the merge request page
  2. Choose a merge method:
    • Merge Commit - Creates a merge commit
    • Squash - Combines all commits into one
    • Rebase - Applies commits on top of target
  3. Optionally delete the source branch
  4. Click Confirm Merge

Conflicts

Conflicts occur when the same part of a file was changed in both branches.

How Conflicts Happen

  1. You create a branch and modify @R1
  2. A teammate also modifies @R1 on main
  3. When you try to merge, there's a conflict

Detecting Conflicts

Paplix automatically detects conflicts when:

  • A merge request is created
  • The target branch is updated

You'll see a warning on the merge request page if conflicts exist.

Resolving KiCad Conflicts

Paplix provides visual conflict resolution for KiCad files:

  1. Click Resolve Conflicts on the merge request
  2. For each conflicting file, you'll see:
    • Your Version - Changes from your branch
    • Their Version - Changes from the target branch
    • Common Ancestor - The original version

Resolution Options

For each conflicting component, choose:

  • Keep Mine - Use your version of the component
  • Keep Theirs - Use their version
  • Keep Both - Include both versions (careful with duplicates)
  • Keep Neither - Remove the component entirely

Committing Resolution

After resolving all conflicts:

  1. Review the merged result
  2. Click Commit Resolution
  3. The merge request can now be merged

Best Practices

Avoid Conflicts

  • Communicate - Let teammates know what you're working on
  • Pull Often - Keep your branch updated with main
  • Small Changes - Make frequent, small commits
  • Separate Concerns - Work on different parts of the design

When Conflicts Occur

  • Don't Panic - Visual resolution makes it manageable
  • Understand Both Sides - Review what each change intended
  • Test After Resolution - Verify the merged design works
  • Ask Questions - Reach out to the other contributor if unclear

Conflict Types

Component Value Conflicts

Both sides changed the same component's value:

  • Example: You changed @R1 to 10K, they changed it to 4.7K
  • Resolution: Pick the correct value based on design requirements

Position Conflicts

The same component was moved to different locations:

  • Example: You moved @U1 left, they moved it right
  • Resolution: Choose the better placement or a compromise

Addition/Deletion Conflicts

One side added a component, the other deleted related components:

  • Example: You added @C5, they removed @C4 which @C5 depends on
  • Resolution: Decide if the addition is still valid

Tips

  • Use descriptive branch names (e.g., add-usb-port)
  • Write clear merge request descriptions
  • Review diffs before creating a merge request
  • Resolve conflicts promptly to avoid blocking teammates

Next Steps