Sulkta-Coop/element-x-ada
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: add SYNC.md explaining repo topology + upstream sync procedure

Browse source
This commit is contained in:
Cobb 2026-04-16 21:00:29 -07:00 • committed by Kayos
parent 2d8df4f23f
commit 84519ab6c9
1 changed files with 78 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

78
SYNC.md Normal file
View file

@ -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.