david.boston / ultimate-tool
Hardware-in-the-loop development platform for the Commodore 64.
Star
Fork 0
Watch
ultimate-tool CONTRIBUTING.md
5.5 kB
Markdown
at main

Contributing to Ultimate Tool #

Thanks for helping improve Ultimate Tool. This project is developed with a risk-driven, evidence-driven method, so the most useful contribution is a bounded, verified slice rather than a broad framework.

License and contribution terms #

Ultimate Tool is free software licensed under the GNU General Public License, version 3 or (at your option) any later version (see LICENSE). By contributing, you agree that your contribution is licensed under the same terms. Do not contribute code or assets you cannot license this way.

Read the project rules first #

AGENTS.md is the authoritative contributor and agent instruction file. It defines the product direction, the development loop, the hardware rules, the contract/data rules, and the change discipline. Read it before proposing a change.

Note on packaging: the public source package may exclude AGENTS.md, but the link above is valid inside this public repository. Release archives use a separately reviewed source allowlist; raw local evidence and credentials must never be committed or included in a public release. The project-level rules still apply to every change.

The product decision is DEVELOPER_PLATFORM_VISION.md (authoritative when documents overlap), with ULTIMATE_CAPABILITY_RESEARCH.md as supporting research.

Development loop #

For each product slice:

  1. State the user-visible outcome and acceptance criteria.
  2. Identify the riskiest unverified assumption.
  3. Run the smallest experiment that can prove or disprove it.
  4. Implement the complete build-to-evidence path.
  5. Test deterministic behavior with the fake target.
  6. Verify emulator behavior in VICE.
  7. Verify hardware-dependent behavior on the intended physical device.
  8. Preserve useful evidence for both success and failure.
  9. Refactor shared contracts only after the slice works.
  10. Document behavior that was actually observed.

A feature is not complete merely because an API request, upload, or launch command succeeded.

Hardware permission rules #

Hardware access is never assumed. When a change touches a physical device:

  • Start with read-only discovery and identity checks.
  • Confirm the intended product, hostname, firmware, FPGA/core version, and enabled services before any mutation.
  • Treat deployment, reset, input injection, memory writes, configuration changes, firmware operations, and power operations as separate capabilities that each require their own explicit permission. Destructive or ambiguous operations are never retried.
  • Report transport success separately from observable program success, and require real-hardware evidence for any display, input, audio, raster, timing, drive, or UCI claim.
  • Never store credentials in manifests, logs, run records, evidence bundles, fixtures, or command history. C64U_PASSWORD stays server-side and out of arguments.
  • Keep Ultimate trusted-LAN services off untrusted networks.

Do not run hardware acceptance work as part of ordinary checks, and do not put device access or credentials into CI.

Building and testing #

Requirements: Rust 1.93 (with rustfmt and Clippy), Make, and Node.js 22. Playwright and Python are needed only for their respective check layers.

Fast host checks (formatting, strict Clippy, locked workspace tests, dashboard helper tests, whitespace check):

make check

Full host, Python, and browser checks:

make check-all

check-all runs check, then check-python (python3 -m unittest discover -s tests/python -v), then check-browser. The browser layer needs its own setup because the frontend has no Node runtime dependency and no bundling step:

npm ci
npm run setup:browser
make check-browser

Linux browser libraries may also be required; follow the official Playwright browser setup and do not assume a successful browser download installed the operating-system libraries.

The Python layer drives the first-run example and its snapshot checks. It does not compile C64 source.

Fixtures, VICE, and Docker #

Rebuilding the C64 fixtures needs Docker and the pinned Rust-MOS image. make test-vice additionally needs VICE 3.8. These are separate gates from the fast host and Python checks:

make fixture
make test-fake
make test-vice

See TESTING.md for what each layer does and does not prove. The planned release, checkpoint fixture, packaged runtime, and public pipeline gates are recorded as that work is implemented; this document does not claim those future gates have passed.

Scope discipline #

Do not expand into new native targets, toolchains, or hardware behaviors without a validated workflow that needs them. Keep future ideas in ROADMAP.md or the research document instead of partially implementing them in the core. Prefer explicit errors over silent fallback, and do not add an abstraction without a current consumer or a proven near-term need.

Change discipline #

  • Inspect the current implementation and Git state before proposing changes.
  • Preserve unrelated user changes.
  • Keep commits and patches bounded to one coherent slice.
  • Do not claim support that has not been demonstrated.
  • Label experimental behavior and undocumented firmware assumptions clearly.
  • Update acceptance criteria and documentation when verified behavior changes.