diff --git a/docs/plans/2026-07-05-firmware-fork-dt-migration.md b/docs/plans/2026-07-05-firmware-fork-dt-migration.md new file mode 100644 index 0000000..f1f8db0 --- /dev/null +++ b/docs/plans/2026-07-05-firmware-fork-dt-migration.md @@ -0,0 +1,96 @@ +# Firmware fork → DT Gitea migration + clean RRG-tracking model + +**Status:** Planned, not started · **Date:** 2026-07-05 · Related: [2026-07-03-firmware-upstream-rebase-plan.md](2026-07-03-firmware-upstream-rebase-plan.md) + +## Goal + +Host pm3py and its Proxmark3 firmware fork on the DT Gitea, customize the firmware, +and pull RRG (`RfidResearchGroup/proxmark3`) updates **without ever touching the RRG +version** — via the standard **rebase-fork** model. + +## The model + +One firmware repo, `/proxmark3`, with a strict branch split: + +| Branch | Role | +|--------|------| +| `master` | **pristine RRG mirror** — only ever fast-forwarded from `upstream`, never our commits | +| `pm3py` | our customizations (atomic single-file commits) on top of `master`; the submodule pins this | + +Remotes: `origin` = `/proxmark3` (SSH), `upstream` = RRG (already configured). +pm3py itself moves to `/pm3py`; its `.gitmodules` points at the `pm3py` branch. + +Why rebase-fork (not merge / subtree / quilt): our ~33 patches already *are* a hand-managed +atomic-commit patch queue; rebase is the native git form. It keeps `git diff master..pm3py` +a clean picture of exactly our changes, and resolves the recurring `iso15693.c` conflict +(24/33 commits touch it) **once** per update instead of on every merge. + +## The three real gotchas (all handled) + +1. **Gitlink must be published or fresh clones dangle.** The firmware `pm3py` tip must be + pushed *before* pm3py's gitlink references it (Phase 6 before 7). +2. **The uncommitted EML host-poll change is in no ref** — it would be silently lost on any + checkout/reclone. Backed up (`scratchpad/eml-hostpoll.patch`) and committed on `pm3py` + in Phase 5. +3. **Our history is intermixed with upstream merges** — `merge-base(main, upstream/master)` + is only 11 commits below HEAD, so 48 of our 59 commits sit *below* it in the upstream DAG. + A naive `rebase --onto master $MB pm3py` would carry only the top 11 and **drop 48**. So + the migration does **not** rebase — it mirrors everything verbatim and defers the clean + split to the first upstream pull (see Ongoing). + +## Migration runbook (no rewrite, no data loss) + +Split by **who**: `[A]` = I do it locally (offline); `[U]` = you run it (Gitea web / pushes, +since my sandbox can't reach `:20022`). + +- **Phase 0 [A] — safety net:** back up the EML diff (done); tag every must-preserve head + `bak/`; `git bundle create --all` for both repos. +- **Phase 1 [U] — create EMPTY DT repos** `/proxmark3` and `/pm3py` (no + README/license — a first commit blocks a mirror push). +- **Phase 2 [A] — materialize local heads:** `git branch pm3py main` (verbatim), and local + branches for the 6 feature branches. No rebase. +- **Phase 3 [U] — mirror-push firmware:** `git fetch upstream master` then + `git push --mirror ssh://git@git.dngr.us:20022//proxmark3.git` (safe: target empty). +- **Phase 4 [U] — seed `master`:** `git push
refs/remotes/upstream/master:refs/heads/master`. +- **Phase 5 [A] — commit EML on `pm3py`, repoint config, bump gitlink:** commit the EML + host-poll; rename firmware `origin`→`mikefaith-backup`, add DT `origin`; set `.gitmodules` + `url`=DT SSH + `branch=pm3py`, `submodule sync`; `git add .gitmodules firmware` + commit. +- **Phase 6 [U] — publish the firmware tip (CRITICAL):** `git push origin pm3py`. +- **Phase 7 [U] — mirror-push pm3py + repoint origin** to `/pm3py`. +- **Phase 8 [U] — VERIFY** a fresh `git clone --recurse-submodules` of `/pm3py`: + submodule resolves (no "reference is not a tree"), `make PLATFORM=PM3GENERIC` + `pytest` + pass, then a hardware smoke test. +- **Phase 9 [U] — retire old repos** (ARCHIVE read-only, never delete) only after Phase 8. + +Rollback at any point: nothing is rewritten/deleted, so `git remote rename mikefaith-backup +origin` restores the pre-migration state; the old repos and the Phase-0 bundles are the +backstop until Phase 8 passes. + +## Ongoing: pull RRG updates without impacting RRG + +``` +git -C firmware fetch upstream master +git -C firmware push origin refs/remotes/upstream/master:refs/heads/master # ff-only, pristine +# rebase our patches onto the new base in an isolated worktree, build+test, then: +git -C firmware push origin rebase-wip:pm3py --force-with-lease # only our branch, leased +cd && git add firmware && git commit -m "chore(firmware): rebase onto RRG , bump gitlink" +``` +`master` is append-only (never rewritten); only `pm3py` is force-pushed, always with a lease. +The **first** pull also does the deferred clean split: enumerate our commits +(`git log --author=michael --author=dangerous-tac0s upstream/master..pm3py`), skip +already-upstreamed ones (hf-mfu-esetblk PR #3404), and rebuild `pm3py` as an explicit +patch series onto fresh `master` — validate `git diff pm3py` shows only deltas +upstream lacks. Later pulls are the simple linear `rebase --onto` case. See the 2026-07-03 +plan for the per-file conflict detail (`iso15693.c` hot spot). + +## Inputs needed from you + +- The **DT org name** on git.dngr.us (substitutes ``). +- Fork default branch: recommend `master` (matches RRG). +- Confirm your SSH key has write in the `` namespace. + +## Provenance + +Multi-agent workflow (strategy eval + state audit + topology design → synthesized runbook). +The adversarial data-loss verify pass was cut short by a rate limit; the mirror-to-empty-repo +safety, publish-before-reference ordering, and EML backup were re-checked by hand. diff --git a/docs/plans/README.md b/docs/plans/README.md index 19541d5..d786716 100644 --- a/docs/plans/README.md +++ b/docs/plans/README.md @@ -47,6 +47,7 @@ approach, concrete steps, tests, risks. | Plan | Status | Summary | |------|--------|---------| | [2026-07-03-firmware-upstream-rebase-plan](2026-07-03-firmware-upstream-rebase-plan.md) | 📎 | Rebase the `proxmark3-pm3py` fork against upstream PM3 (atomic single-file-commit workflow). | +| [2026-07-05-firmware-fork-dt-migration](2026-07-05-firmware-fork-dt-migration.md) | 📋 | Migrate the firmware fork + pm3py to the DT Gitea; clean `master`(RRG-mirror)/`pm3py`(patches) rebase-fork model. | ---