Take theirs, the release branch is newer

Lab machine

A private Linux machine with the problem already set up. Sessions last up to 60 minutes.

Dmitri Vos opened REL-250 at 15:30task

The 2.5.0 release merge stopped on a conflict in the release notes. The deploy freeze lifts in 30 minutes, and the release channel says to take theirs.

Both branches changed the same part of the release note for good reasons. The release branch moved it to 2.5.0. While it was open, main changed the note for a reason of its own. Find out what, and why, before you resolve anything.

"Just take theirs, the release branch is newer." (release channel)

Taking either side whole loses the other side's reason. The release note is the document someone will follow at 3 a.m. if 2.5.0 goes wrong.

Your task

Resolve RELEASE_NOTES.md so it describes 2.5.0 and its rollback uses shipctl with the 2.4.0 artifact, keep both branches' other changes, pass the release-note gate, and commit the merge.

On the machine

repo/ with the merge in progress on main
git log --merge -p -- RELEASE_NOTES.md: why each side changed the line
scripts/check-release-note.sh, the release-note CI gate

Timeline

MonMain replaces waybill-deploy with shipctl: the old tool exits 0 without rolling back.

Tuerelease/2.5 updates the rollback target to 2.4.0, still using waybill-deploy.

15:28git merge release/2.5 stops on RELEASE_NOTES.md.

15:30"Just take theirs." Freeze lifts at 16:00.

Done when

The committed note describes 2.5.0 and its artifact digest.
Its rollback command returns to the 2.4.0 artifact, with the tool main's runbook says to use.
The merge is committed on main with no conflict markers left.
What main changed in the note while release/2.5 was open survives, and so do both branches' other changes.

How it is checked:The checker requires a committed merge on main with both parents and no conflict markers. The 2.5.0 note must name the 2.5.0 digest, keep main's change (the shipctl rollback tool, or the new registry host), roll back to the 2.4.0 digest, and pass the repository's release-note gate, with both branches' other files intact.

Passed. Here is how others fixed it

This lab has 2 versions. Reset for a fresh machine, and you may get a different one.

Break it for a friend. Pick the version they get, and the link is copied for you to send: version 1 · version 2

Other fixes that also pass:

Resolve with `git checkout --conflict=diff3 RELEASE_NOTES.md` to see the common ancestor, then hand-edit the result.
Use `git mergetool` with a three-way view; the important part is reading both sides' history before picking a line.

Fixes that look right but are not:

Selecting “ours” and silently dropping the release branch's version, digest, and rollback target.
Taking “theirs”, which silently undoes main's change: a retired tool that exits 0 without rolling back, or a registry that is shutting down.

Why it broke. A conflict marker is a request for a human to decide what both changes meant, not permission to choose one entire side. The release note is the document someone follows at 3 a.m. if 2.5.0 goes wrong, so it has to carry the release branch's facts and main's corrections together.

How Mara worked it

git status and git diff
Which file conflicts, and the two versions of the line.
git log --merge -p -- RELEASE_NOTES.md
Why each side changed it. Both reasons are real.
Write the lines with both changes
Neither "ours" nor "theirs" is right on its own.
scripts/check-release-note.sh
The release CI gate, run before you commit.
git add RELEASE_NOTES.md && git commit
Conclude the merge. No markers left, both branches' other changes kept.

Hints

Hint 1

Read both changes, not just “ours” and “theirs.” `git log --merge -p -- RELEASE_NOTES.md` shows why each side changed the line.

Hint 2

What main changed and what the release branch changed are independent facts, even when they touch the same line.

Hint 3

The right line takes main's change and the release branch's change together.

Hint 4

Run the repository's release-note gate before you commit.

Show the solution

Read why each side changed the conflicting line: `git log --merge -p -- RELEASE_NOTES.md`. The release branch moved the note to 2.5.0 (new version, new artifact digest, rollback to 2.4.0). Main changed the same lines for an unrelated reason: it replaced the retired `waybill-deploy` with `shipctl`, or moved the artifact to the `cr.northstar.example` registry. Write the lines with both changes, run `scripts/check-release-note.sh`, `git add RELEASE_NOTES.md`, and `git commit` to conclude the merge.

Version Control with Git

Branching, merging, and conflicts

What a merge actually combines, why conflicts happen, and how to resolve one so that both intentions survive.

A branch is a line of commits

Creating a branch makes a new pointer at the current commit. As you commit, that pointer moves and the original stays put. Two people working "on main" each have a local main that moves independently. Pushing and pulling reconcile them, and that reconciliation is a merge or a rebase.

How a merge decides

Merging branch B into A, Git finds the merge base, the nearest commit both share. It then compares base→A and base→B:

Regions changed on only one side take that side's version automatically.
Regions changed identically on both sides are fine.
Regions changed differently on both sides are conflicts.

If A has no commits since the base, there is nothing to combine, so Git just moves A forward. That is a fast-forward. Otherwise it records a merge commit with two parents. Teams that want every feature visible as a unit use --no-ff to force a merge commit.

Reading a conflict

A conflicted file contains markers:

<<<<<<< HEAD
version: 2.4.1
rollback: deployctl rollback --to 2.4.0
=======
version: 2.4.0
rollback: deployctl undo
>>>>>>> fix-rollback-command

The markers show the two results but hide the base. Without it you cannot tell who changed what. Switch to the three-way view, git checkout --conflict=diff3 RELEASE.md or permanently git config merge.conflictStyle diff3 (zdiff3 on recent Git), and a third section shows the original. Now it is clear that one branch bumped the version and the other fixed the rollback command. The correct resolution keeps both changes. Picking a side throws away a colleague's fix and makes the release note wrong in a way no tool will flag.

The workflow:

git status lists conflicted paths.
For each, read base, ours, and theirs, and decide what the combined truth is.
Edit the file to that truth and remove all markers.
git add the file, then git commit (or git merge --continue).
Build and test. Textually clean merges can be semantically broken.

If you lose the thread, git merge --abort returns you to where you started.

Rebase: replaying instead of joining

git rebase main takes your branch's commits and replays them one by one on top of main, which gives a linear history. Each replayed commit is a new commit with a new ID. Conflicts are resolved per replayed commit, followed by git rebase --continue.

Pro Git states the rule plainly: do not rebase commits that exist outside your repository and that others may have built on. Rebasing a private feature branch before review is tidy. Rebasing main after colleagues have pulled it forces everyone to untangle duplicated history. Shared branches move forward through merges or reverts, not rewrites. The “Releases, tags, and shared history” notes revisit this with force-pushes.

Keep branches short

Most painful conflicts come from long-lived branches that drift from main. Small branches merged often keep each merge base recent and each conflict small enough to understand. That is a delivery practice as much as a Git one, and the Continuous Delivery track returns to it as trunk-based development.

Key terms

Merge base: The most recent common ancestor of the two commits being merged. Each side's changes are measured from it.
Fast-forward: A merge where the target has no new commits, so Git just moves the branch pointer forward. No merge commit is created.
Conflict: Both sides changed the same region of a file relative to the base, so Git cannot choose automatically.
Rebase: Replaying commits on top of another base, which produces new commits with new IDs.

Read further

Pro Git, 2nd edition, 3.2 "Basic Branching and Merging" and 3.3 "Branch Management" (Free to read online (CC BY-NC-SA 3.0))
The difference between a fast-forward and a merge commit, the conflict markers, and git mergetool. Note what git branch --merged tells you.
Pro Git, 2nd edition, 3.6 "Rebasing" (Free to read online (CC BY-NC-SA 3.0))
How rebase replays commits on a new base, and the section "The Perils of Rebasing" with its rule about commits that exist outside your repository.
Pro Git, 2nd edition, 7.8 "Advanced Merging" (Free to read online (CC BY-NC-SA 3.0))
Aborting a merge, ignoring whitespace, viewing the base version of a conflicted file, and diff3 conflict style. It turns guessing into reading.

Take theirs, the release branch is newer REL-250