mirror of
https://github.com/jkdansereau/goldeneye-pc-port.git
synced 2026-10-24 00:02:45 +02:00
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.
66 lines
3.1 KiB
Markdown
66 lines
3.1 KiB
Markdown
# 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
|
|
|
|
1. **The decompilation is not modified for the port.** Everything under `src/`
|
|
and `include/` 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 in `port/`.
|
|
|
|
2. **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 — see `docs/dev-process.md`'s rule-2 sign-off
|
|
procedure; it is not something a contributor can self-approve or infer
|
|
from this exception.
|
|
|
|
3. **Region macros mirror the Makefile.** `CMakeLists.txt` `REGION_DEFS` must
|
|
match the N64 `Makefile`'s per-region macro set exactly.
|
|
|
|
4. **Verify before you push.** A build-affecting change needs, at minimum, a
|
|
clean configure + build for `ntsc-final` and a crash-free run of one level
|
|
(`./build-pc/ge007.x86_64 -level_09`).
|
|
|
|
## Style
|
|
|
|
- C/C++ formatting follows `.clang-format` and `.editorconfig` in 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 `--version` output; 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.
|