Contributing

Ishtaria is built to be extended by people who play it. This page is for you if you want to add a spell, a crop, a quest, a town, a mechanic or a fix.

Note

The primary source of Ishtaria is git.vitexsoftware.com/Ishtaria (Forgejo). The repositories on GitHub (github.com/Vitexus) are a secondary mirror, and packages and binaries are not built from GitHub. See Repositories.

Before you start

  1. Read Project rules that never change. They are short, and a pull request that breaks one is not merged.

  2. Run a private world (Local development setup) and play with the thing you want to change.

  3. Look at the Cookbook: adding things to the game: most additions are a data file, a migration, a translation and a test, not a new system.

  4. Discuss a larger change in an issue first. An architectural one (a new kind of effect, a new persisted contract, a change of an ADR) is written as a decision record (Decision records) before the code.

Working with Claude Code

Every repository has a CLAUDE.md that Claude Code reads at the start of a session; it holds the commands, the rules and the map of that repository. A good session looks like this:

  1. Open Claude Code in the repository you are changing and describe the behaviour you want, not the files. Ask for a plan first (plan mode) for anything that spans server and client.

  2. Let it read the cookbook entry for your kind of change and the nearest existing example. Prefer “do it the way trade.rs does it” to a new pattern.

  3. Make it run the checks (fmt, clippy, tests) and show the output. Ask what it could not verify; for anything visible, run the client and look.

  4. Review the diff yourself. Generated code is your code: read the SQL, the locking, the validation, and every place where a client value reaches the server.

  5. Keep the change small and in one repository where possible. Cross-repository changes (a server route and its client) go in linked pull requests.

Things a generated change must never do: weaken or skip a failing test, edit a released migration, trust a client value, log a secret, add a dependency without a reason, or describe an unfinished feature as finished.

Definition of done

A change is ready when

  • cargo fmt --check, cargo clippy --locked --all-targets -- -D warnings and the tests pass (server, core, worldgen), or the make test-... targets of the client you touched pass;

  • the change has a test that fails without it, including the refusal paths (not enough mana, too far, not yours, dead, twice in a row);

  • new text is in client.csv in English and Czech, new assets have their licence recorded, and the READMEs, etc/ consistency tests and, for a contract, the documentation are updated;

  • the pull request says what was tested, what was not, and what remains planned.

Conventions

  • Commits are small and follow Conventional Commits (feat(ishtaria-server): ...). The default branch is main.

  • Rust: cargo fmt and clippy -D warnings clean; errors are controlled Error::Status values; no unwrap on request data.

  • GDScript: typed where Godot can infer it, no await without a test that would catch an error, every server answer validated.

  • Protocol changes need an updated schema, an example and a passing tests/validate_examples.py.

  • Documentation is English. Czech translation of the game is welcome in locales/client.csv; of this documentation through sphinx-intl (locale/cs).

  • By contributing you agree to license your work under the repository’s licence (Repositories).

Security

Report a vulnerability privately as described in SECURITY.md of the repository, not in a public issue. Never put a token, a password or a private key in an issue, a log or a screenshot.