diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..d9fe837 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,87 @@ +# Pumptools contributor instructions + +These instructions apply throughout the repository. Read the relevant source, +tests, and documentation before changing behavior. See `CONTRIBUTING.md`, +`doc/development/development.md`, and `doc/development/architecture.md` for the +broader contributor guidance. + +## Engineering principles + +- Follow the patterns in neighboring code for naming, ownership, lifecycle, + error handling, logging, documentation, and CMake organization. +- Keep each responsibility in the narrowest existing module. Reusable + corrections belong in a suitable patch module; game hooks select and + initialize the modules required by that game. +- Preserve API return values and `errno` behavior. Use module-scoped logging for + runtime failures and assertions for internal invariants. +- Preserve pass-through behavior when a hook does not own or recognize a call. +- Treat constructors, destructors, `__libc_start_main`, `dlopen`, `dlsym`, + `RTLD_NEXT`, signatures, calling conventions, hard-coded addresses, + initialization and shutdown order, recursion, and thread safety as + compatibility-sensitive boundaries. +- Follow `.clang-format` for maintained C and header files. Inspect the focused + diff before running `make clang-format`, and do not format vendored code under + `src/imports/`. Follow the established local style for CMake, Make, shell, and + Markdown files. +- Comments and documentation should explain non-obvious constraints, ABI or + lifecycle requirements, and reasons. Update user or development documentation + when configuration, public APIs, setup, or supported behavior changes. + +## Tests and hooked behavior + +- Add or update unit tests whenever changed behavior can be isolated with the + existing test framework. For a bug fix, add a regression case that + demonstrates the previous failure where practical. +- Preserve coverage for existing behavior while testing the new expectation. + Include relevant success, failure, malformed-input, disabled, no-match, and + pass-through cases. +- Check observable behavior as applicable: parameters, calls, buffers, return + values, `errno`, side effects, lifecycle, and ownership. Do not merely relax + an expectation to accommodate a changed implementation. +- Put production behavior in the production module and exercise that same code + from tests. Do not create a test-only copy of parsing or decision logic. +- For hook behavior, use the capnhook named-function-mock seam and CMocka when + the dependency can be isolated. Verify whether and how the original function + is called, then keep the real game-hook path responsible for initializing the + tested patch module. +- `src/main/hook/propatch/usb-fix.c` and + `src/test/hook/propatch/usb-fix/main.c` provide the established pattern for a + production patch integrated with mocked detoured calls. +- Register new tests in the corresponding `cmake/src/test/` hierarchy. + +## Verification + +Run the applicable checks from the repository root: + +```sh +make build +make test +make build-docker +``` + +Compilation, unit tests, Docker compatibility builds, fixture or process tests, +game-runtime tests, and cabinet or hardware tests are separate evidence levels. +Do not claim game or hardware compatibility from compilation or unit tests. +State what was actually tested and the relevant platform, game, and hardware +details. + +## Maintainer interaction and LLM use + +Follow the LLM policy in `CONTRIBUTING.md`. Human contributors remain +responsible for understanding, reviewing, testing, and validating submitted +work. + +Do not autonomously publish issues, pull requests, reviews, comments, or +replies. Prepare concise drafts for human review. Filter analysis and tool +output to evidence relevant to the discussion rather than transferring raw or +excessive output to maintainers. A human must choose what to communicate, +provide its context, guide the discussion, and respond to maintainer feedback. + +Only describe work as an unvetted or deliberately rough prototype when the +maintainers have agreed to receive it on that basis. Clearly state its scope, +limitations, and verification status. + +## Sensitive material + +Do not read, reproduce, log, or commit credentials, game assets, dongle keys, +raw security material, private identifiers, or unsanitized runtime evidence. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2ff73f0..28d478b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -12,6 +12,28 @@ we have, the easier it might get to solve the issue. When creating new issues, use our template for reporting bugs. It tells you what kind of information we need. +# Use of LLM tools + +Using large language models and other generative tools is allowed. The person using the tool remains responsible for +the contribution and its communication. + +LLMs should assist with work that the contributor understands well enough to direct, review, and validate. They may +perform implementation, research, analysis, documentation, or other leg work, but the contributor must check their +output before submitting it to maintainers. The usual requirements for correctness, testing, documentation, security, +and compatibility apply regardless of how the work was produced. + +An exception may be made when the maintainers have agreed in advance to receive an explicitly unvetted or deliberately +rough prototype. Its purpose, limitations, and verification status must be clear. + +Interactions with maintainers in issues and pull requests must be actively driven by a human. Reviewed LLM-generated +material may be included directly when it usefully communicates code analysis, technical explanations, test results, +or similar evidence; rewriting it solely to conceal its origin is not required. However, a human must decide what is +relevant, provide the surrounding context, initiate and guide the discussion, and respond to maintainer feedback. + +Do not use an LLM or automated agent to autonomously post comments, reviews, or replies, or to flood maintainers with +unfiltered output. Contributions and discussions should present concise, relevant, human-reviewed information rather +than transferring the burden of reviewing raw LLM output to the maintainers. + # Pull requests: bugfixes, new features or other code contributions Pull requests are welcome! May it be a PR to an already known issue or a new feature that you consider as a valuable @@ -32,4 +54,4 @@ changes, once approved, will be included in the next release. # Roadmap -No concrete roadmap or timeline exists. When the time is right, we continue adding support for newer games as well. \ No newline at end of file +No concrete roadmap or timeline exists. When the time is right, we continue adding support for newer games as well.