Ransom-s-wake/CONTRIBUTING.md

Contributing to Ransom's Wake

Definition of ready

Before implementation, a change must identify:

• the player-visible outcome;
• the owning production layer;
• the authoritative source of state;
• the behavior that will prove completion;
• any save, input, accessibility or performance consequence.

If ownership is unclear, resolve it before writing code. If a change introduces a new dependency direction or global service, write an ADR first.

Definition of done

A change is complete only when:

• no second implementation of the same rule exists;
• public boundaries use explicit typed data;
• unit tests cover new domain behavior;
• integration tests cover changed scene or service wiring;
• every corrected bug has a regression test, or a documented reason why not;
• error and empty states are handled;
• relevant documentation and baselines are updated;
• bash scripts/quality_gate.sh passes from the repository root.

Visual behavior additionally requires a check at 1280 × 720 and at the smallest supported in-game presentation size. Human readability cannot be inferred from mesh counts or screenshots alone, so playtest observations remain evidence.

Change discipline

• Keep one conceptual change per commit.
• Prefer deletion or extraction over parallel implementations.
• Do not rename and redesign unrelated systems in the same change.
• Never modify generated .godot/ content.
• Keep assets separate from gameplay state and reference them through resources.
• Treat warnings, leaked nodes and nondeterministic tests as defects to triage, even if the process returns exit code zero.

Review checklist

• Is there exactly one owner for each new rule?
• Does dependency flow match docs/ENGINEERING_GUARDRAILS.md?
• Can the domain behavior run without a scene tree?
• Can UI code only observe or issue commands?
• Are time, randomness and external I/O controllable in tests?
• Is failure behavior tested?
• Is a prototype implementation being copied instead of translated?
• Would a future save migration be required?
• Does the quality gate pass?