ContributeExplanationFor contributorsApplies from 4.4.0
Welcome
Cette page en françaisThis page on the GitHub wiki
quest'n'click is a small project with one maintainer, @wanoo. A contribution is welcome when it is small, tested and explained: a bug fix with its regression test, a missing case of the validator, a clearer page. This page says why the project works the way it does; the pages it links say how.
Why the project works this way
A game is data, never code. The engine in src/engine/ reads a game folder games/<id>/ and knows nothing else
about it. That is what lets the validator, the solver, the replay, the Studio and an AI assistant all read and check the
same content. A change to the engine keeps that promise: gameplay stays declarative in games/<id>/, and geometry
stays in layout/*.json (see Architecture).
Most mechanics already exist. Before asking for a new command or field, read the classic mechanics of the genre
(Classic mechanics, the old docs/en/CLASSICS.md): insult fights, melting items, patrols,
haggling and cross-character puzzles are combinations of rules, flags, scripts and events the engine already has. A
request for something new starts from the feature issue template, after that page.
Every claim has a check. The project prefers a gate that fails to a promise that drifts. Coverage floors only rise (The coverage ratchet), the engine's behaviour is frozen in a baseline (The quality baseline), and every surviving mutant is named with its reason (Mutation testing). What only people and real devices can check is a field pass, reported in each release (Field passes).
What is public is a promise; the rest may move. The public DSL, the save envelope and the plugin contracts follow semantic versioning from v3 on, except on the 4.1.8–4.1.15 incubation line, where a break was documented with a migration (Stability and support). Internal modules are not compatibility promises unless a page says otherwise (Import boundaries).
How a contribution goes
- Prepare the machine once: Developer setup.
- Read the code with Architecture, then walk the Code tour (half an hour).
- Change one thing, with the loop of The dev loop. Keep it small; a bug fix comes with the test that would have caught it.
- Name the branch, the pull request and the fragment of the CHANGELOG as Conventions says.
- Run the checks of Before a pull request, open the pull request from the template, and read what CI says (CI explained).
Working with an AI assistant is expected and has its own rules: Contributing with AI agents.
Conduct and security
Everyone here follows the Code of conduct. A vulnerability is reported privately, never in a public issue: Security policy. How decisions are made, and who makes them, is in Governance and Decisions and ADRs.