James Dansereau
1c60da6f46
Widens the written scope of AGENTS.md non-negotiable #2's ABI exception to match established practice (runtime struct/union misreads, not just ROM-serialized structs — the D209/D210/D255 pattern), states explicitly that diagnosis into src/game is never restricted (only the fix is), and defines a real three-bucket taxonomy + sign-off procedure (dev-process.md §7) for the rare genuine-behavior-difference case, replacing the undefined ad hoc "ask the user" gesture that's been referenced without being defined across ~10 places in the docs. Mirrors the same framing into CONTRIBUTING.md and the PR template for external contributors. Extends porting-notes.md §A1 with D255 as a third worked example and a tell-tale-signs checklist, explicitly distinguishing it from D284 (same epistemic shape, different mechanism, no rule-2 question at all). Appends a ready-to-dispatch pass-10 brief to the D236 entry applying the new taxonomy to its actual next step. Docs-only; no code/build changes. Per docs/dev/notes/RULE-2-CLARIFICATION-PLAN.md.
3.1 KiB
Contributing
Thanks for your interest. This is a small hobby project; issues and pull requests are welcome, but please read the ground rules first — they are what keep the port faithful to the original game.
Ground rules
-
The decompilation is not modified for the port. Everything under
src/andinclude/is compiled unmodified.Makefile,tools/,rsp/,ld/belong to the N64 build and are never touched for PC work. If PC code seems to need a behavioural change in the game, the fix belongs inport/. -
Narrow ABI exception; diagnosis is always allowed. Trace a bug as deep into the decomp's state as the evidence leads — that's never restricted. Only the fix is constrained: the 32→64-bit transition forces a small class of mechanical, semantics-preserving edits — any struct-layout or pointer-width-driven misread caused by 32→64-bit widening, in a ROM-serialized record or a live runtime struct/union alike (see
docs/porting-notes.md§A1 for the pattern and its tells). These are allowed, must be guarded with#ifdef PORT, must change no behaviour, and must be documented. A genuine behavioral difference from real N64 behavior is a separate, much rarer case that needs explicit maintainer sign-off first — seedocs/dev-process.md's rule-2 sign-off procedure; it is not something a contributor can self-approve or infer from this exception. -
Region macros mirror the Makefile.
CMakeLists.txtREGION_DEFSmust match the N64Makefile's per-region macro set exactly. -
Verify before you push. A build-affecting change needs, at minimum, a clean configure + build for
ntsc-finaland a crash-free run of one level (./build-pc/ge007.x86_64 -level_09).
Style
- C/C++ formatting follows
.clang-formatand.editorconfigin the repo root. Match the surrounding code. - Port-layer code is plain C11 / C++17, SDL2 + OpenGL, no extra dependencies.
- Keep commits focused and describe why, not just what.
Forks and derivative works
Fork away — the code is MIT and the port/ layer exists to be extended.
Rebranding, localizing and extending are all welcome, and none of them need
permission. If you carry the work forward under your own name, please keep
two things:
- Attribution. A clear statement, in your README and about page, that the
project derives from this one — with a link. The engine prints its origin at
startup and in its
--versionoutput; keeping that intact is part of the ask. - The record.
docs/dev/(the finding log, porting notes, per-level status) is the engineering record behind every fix. Derivative projects are asked to preserve or link to it rather than fork-and-forget.
Stripping the attribution is the one thing that turns a fork into something we no longer recognize as a descendant of this project.
Where to look
docs/internals.md— how the port is structured.docs/porting-notes.md— the recurring bug classes. Check here before debugging a crash; you are likely looking at a known pattern.docs/dev/— the full finding log and per-level status.