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