git.resolve-version-conflicts

Resolve CDS version-file conflicts

CDS ships many packages, and the cds release group (web, mobile, common, mcp-server) is version-locked. When both master and the current branch bump package versions independently, a rebase (or merge) collides on two file types only:

• packages/<pkg>/package.json — the "version" field
• packages/<pkg>/CHANGELOG.md — the top-of-file version entries

This skill resolves only those two file types mechanically. Anything else that conflicts must be raised to the user.

Prefer re-running the release when the plan is recoverable. Versions and changelog entries are generated by nx release from the version plans in .nx/version-plans/. If you still have the branch's plan file (or can recreate it with yarn nx release plan), the cleanest fix is to take master's side of both conflicted files, restore the plan, and re-run yarn release. Use the manual recomputation below only when that is not practical. See docs/release.md.

When to run

Trigger this flow when EITHER:

1. The user explicitly asks to resolve a versioning / package.json / CHANGELOG conflict, or
2. You organically notice conflict markers (<<<<<<<, =======, >>>>>>>) inside package.json or CHANGELOG.md files during a rebase/merge.

In case 2 you MUST ask the user for confirmation before performing any resolution. Describe what you found (which packages, which files) and ask whether to run this resolution flow. Do not resolve organically-detected conflicts without an explicit go-ahead.

The rules (source of truth)

1. Master's version is the latest. For each package, the version currently on origin/master (equivalently, the HEAD/"ours" side of a rebase) is the newest published version.
2. Reapply the branch's bump on top of master. Determine the type of bump the branch made (patch / minor / major) from the branch's version commit, then apply that same bump to master's latest version. That is the resolved version.
   • patch: x.y.Z → x.y.(Z+1)
   • minor: x.Y.z → x.(Y+1).0
   • major: X.y.z → (X+1).0.0
3. CHANGELOG: put the branch's entry at the top, above master's entries, using today's date and the resolved version, matching the exact format the file already uses. Keep all of master's existing entries intact below it.
4. Only package.json and CHANGELOG.md conflicts are in scope. If any other file is conflicted, STOP and raise it to the user before continuing.
5. Run the formatter when finished.
6. Never change existing commit messages while continuing the rebase.

Step 0 — Confirm scope

git status

List the conflicted (both modified / unmerged) paths. Partition them:

• In-scope: packages/*/package.json, packages/*/CHANGELOG.md
• Out-of-scope: everything else

If any out-of-scope file is conflicted, stop and raise it to the user now. Do not touch those files. Only proceed once the user decides how to handle them.

If you got here organically (not via an explicit user request), also confirm with the user that they want you to run this resolution flow before editing anything.

Note: package.json files often auto-merge cleanly even when the CHANGELOG for the same package conflicts — you must still recompute their versions in the steps below, so include every affected package, not just the ones with visible conflict markers.

Step 1 — Identify the branch's version commit and bump type

The conflict is anchored on a specific commit (during a rebase, git names it in git status as the commit it "could not apply", e.g. 571c39254 (version)).

Inspect exactly what versions that commit changed and by how much:

git show <version-commit> -- '**/package.json'

For each package, read the - "version": "A.B.C" → + "version": "A.B.D" hunk and classify the bump as patch / minor / major (rule 2).

Step 2 — Read master's latest version per package

For every affected package:

git show origin/master:packages/<pkg>/package.json | grep '"version"'

(During a rebase the working-tree/HEAD value equals master's, since master's side was checked out — either source is fine.)

Compute the resolved version = master's latest version + the branch's bump type.

Example from a real run: master was 9.6.9 for all packages; the branch's bump was patch (9.6.8 → 9.6.9); resolved version = 9.6.10 for all of them.

Step 3 — Update each package.json

Set the "version" field of every affected package to its resolved version.

Check whether packages pin each other's versions:

grep -nE '"@coinbase/cds-(common|web|mobile|mcp-server|icons)"' packages/<pkg>/package.json

If internal deps use workspace:^ (the CDS convention), only the top-level "version" field needs changing. If any dep pins an explicit version of a package you just bumped, update that pin to match.

Step 4 — Resolve each CHANGELOG.md

For each conflicted CHANGELOG, produce this order (newest first):

1. Branch entry — heading uses the resolved version and today's date, followed by the branch's change body.
2. Master's entries — kept verbatim below, in descending version order.

Match the file's existing heading format exactly. CDS uses two shapes:

• Real change: ## <version> (M/D/YYYY PST) followed by a #### 🐞 Fixes (or 🚀 Updates, 📘 Misc, …) section and bullet(s).
• Artificial bump: ## <version> ((M/D/YYYY, HH:MM AM/PM PST)) followed by This is an artificial version bump with no new change.

Rules of thumb:

• If the branch's contribution to this package is a real change, carry that change's body into the new top entry (real-change format).
• If the branch only bumped this package to stay in sync (its conflict body reads "artificial version bump with no new change"), keep it an artificial-bump entry; reuse the timestamp from the branch's original entry, with today's date.
• Do not merge the branch's bullet into master's entry — they are separate version entries. Master's entry keeps its own bullets; the branch's bullet lives under the new resolved-version heading above it.

Remove every <<<<<<<, =======, >>>>>>> marker.

Step 5 — Verify no markers remain

grep -rn '^<<<<<<<\|^=======\|^>>>>>>>' packages/*/CHANGELOG.md packages/*/package.json

Expect no output.

Step 6 — Continue the rebase (or commit the merge)

Stage the resolved files and continue without editing commit messages:

git add packages/*/package.json packages/*/CHANGELOG.md
GIT_EDITOR=true git rebase --continue

GIT_EDITOR=true accepts each existing message unchanged. If more conflicts surface on later commits, repeat Steps 0–6; if a later conflict is out-of-scope, stop and raise it.

(For a merge instead of a rebase, git commit --no-edit after git add.)

Step 7 — Format

yarn nx format:write

Step 8 — Report back

Summarize:

• Which commit caused the conflict and which files were in scope.
• The resolved version per package and the bump type applied on top of master.
• The CHANGELOG placement (branch entry on top, master's kept below).
• That commit messages were unchanged.
• That the branch history was rewritten (rebase), so a force push (git push --force-with-lease) will be needed — do NOT push unless asked.