Upstreaming

Upstreaming the Amiga port

Working tracker for getting the AmigaOS 3.x port accepted into upstream micropython/micropython. Captures the contributor-guideline requirements, the acceptance blockers/suggestions, and progress against them. The per-phase design log is on Amiga port design; the test runbook is on Amiga port testing. Snapshot date: 2026-06-21.

Legend: ✅ done · ◐ in progress · ☐ not started · ♻ ongoing responsibility

Generative AI policy

Upstream's ContributorGuidelines § Generative AI policy governs human conduct, not the code — there is no code checklist that makes a PR "compliant". What it requires:

• ♻ The human contributor reads and validates every line before submitting — especially the core py/ changes (asm68k.c/.h, emitn68k.c, the emitnative.c hunks, nlr68k.S).
• ♻ The human engages personally and technically in review — no copy-pasting between maintainers and a chatbot (translation excepted).
• ♻ No AI agent opens or drives the PR autonomously; a human submits it and does the review work.

This port is large and heavily AI-assisted, so it will draw extra scrutiny. The bar is genuine understanding: be able to defend each core hunk from your own knowledge, without a chatbot in the loop.

Acceptance blockers / suggestions

Ordered by impact.

#	Item	Status
1	Split the core py/ native-emitter changes into a separate PR from the port	☐
2	Drop the modjson.c fork; use upstream extmod/modjson.c	✅
3	Curate the commit history (252 commits → small logical set)	☐
4	Remove the sync_upstream.yml fork-maintenance workflow from the PR	✅
5	Open a pre-submission Discussion + state a long-term maintenance commitment	☐
6	Run codeformat.py (uncrustify 0.71/0.72) and ruff format/check, and say so	✅
7	emit68k.c → emitn68k.c (match emitn<arch>.c naming)	✅
8	Key the native-emitter endianness fixes on MP_ENDIANNESS_BIG, not N_68K	✅
9	Move the 68k NLR implementation into py/ + py.mk (where every other arch lives)	✅
10	CI must build all three variants, not just standard (FPU link paths differ)	☐

Notes on the open items

1 — Split the native emitter. Adding a whole new native-code architecture (asm68k.c/.h ≈ 1k lines, emitn68k.c, emitnative.c hunks, the .mpy ABI enum, NLR) is a large, self-contained review that touches the most sensitive part of the tree. Bundling it with the ~9k-line port makes the combined PR much harder to land. Propose the port first with the native emitter disabled, then the 68k backend as a focused follow-up. The existing #if MICROPY_EMIT_68K / #if N_68K guards make that split trivial.

3 — Commit history. Upstream wants small, logical, clean-rebasing commits. Rebase the 252-commit branch into a coherent set (roughly: core py/ changes; the port; tests; examples; CI; docs).

4 — sync_upstream.yml. ✅ Removed. It was fork-maintenance only. ports_amiga.yml (the port build CI) is retained, but expect it to be adapted to upstream CI conventions and a toolchain story they will host.

5 — Discuss first. A new port is a long-term maintenance commitment for the team. Open a GitHub Discussion (or post on Discord) before the PR, outline the port, and state explicitly who maintains it. A surprise mega-PR for a new architecture is the most likely thing to be closed unread.

10 — All variants in CI. Removing floatconv.c from the FPU builds broke the 68040 link (undefined pow/tgamma) during this work — a standard-only CI would not have caught it. Build standard, 68020fpu, and 68040.

Audit findings (no action required)

These were investigated and found acceptable, so they are recorded here to avoid re-litigating them:

• No other obsolete divergence. modjson.c was the only fork of an upstream file. modsocket.c / modos.c / modtime.c are port-original AmigaOS implementations (parallel to ports/unix/), not diverged copies — keep them.
• floatconv.c is legitimate — it overrides bebbo gcc 6.5b's broken soft-float libgcc/clib2 routines and provides the pow/tgamma wraps needed on all variants (libm bugs, not soft-float bugs). It is not the modjson pattern; there is no general fix elsewhere.
• Core py/ diff is clean and well-guarded. 1192 insertions / 3 deletions across 10 files, following the established per-arch backend pattern; every shared-file change is a one-line arch addition or wrapped in #if N_68K, so other ports are provably unaffected. No TODO/FIXME/stub/abort(). The new MP_NATIVE_ARCH_68K enum is appended last (no .mpy ABI renumbering).

Open structural decision

• NLR file shape. The 68k NLR is a standalone py/nlr68k.S plus a C helper py/nlr68k_jump.c, rather than the single naked-asm .c other arches use (nlrthumb.c-style). This is forced: bebbo m68k gcc ignores __attribute__((naked)), so the register save/restore must be hand-written assembly. nlr68k.S is #if defined(__m68k__)-guarded so it is inert on other ports (verified by building the unix port). Upstream may still prefer a different arrangement — worth raising in the Discussion.

Progress log

Work done so far on this branch (commit hashes are on amiga-port):

• 3a63676 — Drop modjson fork in favour of extmod/modjson.c. The fork existed only to dodge an mp_obj_t stack-alignment bug that the general MICROPY_OBJ_BASE_ALIGNMENT = aligned(4) fix already solves. Full extmod json suite + port json smoke test pass (14 tests / 286 cases).
• 888cd94 — Reword modos.c env-var comment to lead with the real-AmigaOS rationale instead of a "Vamos workarounds" heading (comment-only).
• 19f9f72 — Key big-endian native codegen on MP_ENDIANNESS_BIG (prelude index, generator start-offset, code_state.n_state); the n_state shift is now word-width-sized. Native-generator path verified on 68k.
• 40ff324 — Rename emit68k.c → emitn68k.c and move the 68k NLR (nlr68k.S, nlr68k_jump.c) into py/ + py.mk. Both amiga variants and the unix port build cleanly; native/viper/NLR smoke tests pass.
• 301fe33 — Remove sync_upstream.yml fork-maintenance workflow.
• 8f68627 — Apply codeformat.py + ruff format (uncrustify fixes in py/asm68k.h and main.c; ruff reflow of three examples and a smoke test). codeformat.py is now idempotent on the port.
• 1163c0d — Fix codespell findings: rename te → tenc in urequests.py, and skip the auto-generated ports/amiga/modules/_amiga_*.py tables (API names like DoubleClick collide with the dictionary).

Linter status (snapshot)

All three repo-wide linters that gate upstream PRs pass on the port:

• ruff check (lint) — clean.
• ruff format --check — clean.
• tools/codeformat.py -c (uncrustify + fixup_c) — clean and idempotent.
• codespell (2.4.1, CI-style invocation) — clean.