From 9d6b953f76c82327b07576e709382ad7f36f050a Mon Sep 17 00:00:00 2001
From: flupkede <flupkede@gmail.com>
Date: Mon, 21 Sep 2026 12:50:45 +0200
Subject: [PATCH] docs: require a master->develop merge back after every
 release tag

Squash-only release commits leave master and develop without shared
history, so the next release PR is three-way merged against a
pre-squash ancestor and reports phantom add/add conflicts as soon as a
file added since then is edited (hit on v1.4.4).
---
 RELEASING.md | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/RELEASING.md b/RELEASING.md
index e9108db4..2a74902c 100644
--- a/RELEASING.md
+++ b/RELEASING.md
@@ -75,6 +75,28 @@ git push origin v1.0.X
 
 CI (`release.yml`) builds binaries and creates a GitHub Release with auto-generated notes from PR titles.
 
+### 4. Merge master back into develop (immediately after the tag)
+
+```bash
+git checkout develop && git pull
+git merge origin/master -m "chore: merge master (v1.0.X) back into develop"
+git push origin develop
+```
+
+A squash release commit's only parent is master's *previous* tip, so master and
+develop share no history after it and `merge-base` falls back to the last
+pre-squash ancestor. The next release PR is then three-way merged against a tree
+many releases old: every file added since looks independently added on both
+sides, which git auto-resolves only while the two blobs stay byte-identical. So
+the release PR merges cleanly for releases on end, then reports phantom
+conflicts the first time one of those files is edited (v1.4.4, `resident.rs`).
+
+Run it while master's and develop's trees are still identical, when the merge is
+a guaranteed no-op recording nothing but the ancestry — defer it and you inherit
+the very conflicts it prevents. Pushing to develop needs the owner's ruleset
+bypass; going through a PR works too but also fires `bump-develop.yml`, so the
+patch number skips one.
+
 ## Rules
 
 - **Version scheme `Major.Minor.Patch`** (semver):
@@ -90,4 +112,6 @@ CI (`release.yml`) builds binaries and creates a GitHub Release with auto-genera
   release is tagged.
 - **Merge style:** feature→`develop` = **merge commit** (`--merge`); `develop`→`master`
   release PR = **squash** (one commit per release on master)
+- **Merge back after every tag** — `master` → `develop` (step 4), or the next
+  release PR is diffed against a merge base from several releases ago
 - **Tag format**: `v1.0.X` on master HEAD