From 84519ab6c99f0166dedd9660102e97adc344654a Mon Sep 17 00:00:00 2001
From: Cobb <cobb@sulkta.com>
Date: Thu, 16 Apr 2026 21:00:29 -0700
Subject: [PATCH] docs: add SYNC.md explaining repo topology + upstream sync
 procedure

---
 SYNC.md | 78 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 78 insertions(+)
 create mode 100644 SYNC.md

diff --git a/SYNC.md b/SYNC.md
new file mode 100644
index 0000000000..35996377c9
--- /dev/null
+++ b/SYNC.md
@@ -0,0 +1,78 @@
+# Repo topology + upstream sync procedure
+
+This repo is a fork of [`element-hq/element-x-android`](https://github.com/element-hq/element-x-android)
+with a native Cardano wallet module added. The history is structured so that
+staying current with upstream — and one day proposing our additions back —
+stays possible.
+
+## Branches
+
+| Branch | Role |
+|--------|------|
+| `main` | Tracks the upstream commit we are currently based on. Fast-forwarded to `upstream/develop` when we deliberately pull in changes. Nothing coop-specific lives here. |
+| `wallet` | `main` + all our wallet work. This is what we build APKs from. Linear history on top of `main`; rebased whenever `main` moves. |
+| `archive/project-docs` | Frozen snapshot of the planning docs and screenshots that lived on the original orphan `main` branch. Not part of the active graph. |
+
+When we ever want a clean "everything we'd propose upstream" branch, we cherry-pick
+the wallet commits off `wallet` onto a fresh branch rooted at `main`. Because every
+current commit on `wallet` is wallet-module work, that split is simple.
+
+## Remotes
+
+`origin` → this Gitea repo (LAN, via the Rackham SSH tunnel when working remotely).
+
+Add upstream on any local clone:
+
+```bash
+git remote add upstream https://github.com/element-hq/element-x-android.git
+git fetch upstream
+```
+
+## Sync with upstream
+
+When you want to pick up the latest from `element-hq/element-x-android`:
+
+```bash
+# 1. Get the latest from upstream
+git fetch upstream
+
+# 2. Fast-forward main to upstream/develop
+git checkout main
+git merge --ff-only upstream/develop
+git push origin main
+
+# 3. Rebase wallet onto the new main
+git checkout wallet
+git rebase main
+# → resolve conflicts, one commit at a time
+# → conflict surface is small but real: our integration touches
+#   libraries/matrix/{api,impl}, libraries/textcomposer/impl,
+#   libraries/eventformatter/impl, libraries/mediaviewer/impl
+
+# 4. Build + test the APK before force-pushing
+./gradlew :app:assembleFdroidDebug   # or mainnet variant
+
+# 5. Push the rebased wallet branch (force-with-lease, not plain force)
+git push --force-with-lease origin wallet
+```
+
+If the rebase gets ugly, abort and try merging instead:
+
+```bash
+git rebase --abort
+git merge upstream/develop
+# resolves in one shot, one merge commit, less clean history
+```
+
+## Why not a Gitea mirror?
+
+Gitea only lets you configure a pull-mirror at repo-creation time, and mirroring
+a whole repo also means we can't commit to it. We want to keep our own commits,
+so upstream stays as a git remote you fetch from manually.
+
+## License
+
+Upstream is **AGPL-3.0**. Every binary we hand out must be accompanied by the
+corresponding source under the same license. Keeping this Gitea repo accessible
+to recipients of the APK satisfies that. Don't ship binaries without also making
+the source reachable.