Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
149 lines (106 loc) · 8.5 KB

CONTRIBUTING.md

File metadata and controls

149 lines (106 loc) · 8.5 KB
Raw

Contributing to Rust Laboratory: Signal Zero

Thank you for helping improve Rust Laboratory: Signal Zero. The project is a desktop interactive-fiction game built with Rust and Tauri v2. This guide defines the expected workflow for bug fixes, game content, UI work, documentation, and release support.

1. Contribution principles

Contributions should be small, reviewable, and tied to a clear user outcome. A change to a game command must preserve engine state consistency; a change to the desktop UI must keep the Tauri command contract in docs/API.md accurate; and a change to a release workflow must be tested without publishing a release.

Contribution type Preferred first step Primary acceptance signal
Bug report Search existing issues and provide reproduction steps Maintainer can reproduce on a supported platform
Game content Open an issue describing narrative intent and dependencies Content IDs, exits, flags, and item references validate in play
Rust engine change Add or update unit tests in src-tauri/src/game/tests.rs Tests, formatting, and Clippy pass
UI change Describe the command/API contract affected UI handles success, user-facing errors, and empty states
Documentation State the target reader and the behavior being documented Examples match the current source tree

Do not include secrets, access tokens, personal save data, or production credentials in an issue, commit, screenshot, or pull request.

2. Local development setup

Prerequisites

Install the stable Rust toolchain with rustfmt and clippy, a current Node.js runtime for JavaScript syntax checks, and the OS-specific dependencies required by Tauri. The GitHub Actions workflow in .github/workflows/quality.yml is the canonical Linux dependency list.

rustup toolchain install stable
rustup component add rustfmt clippy

On Ubuntu/Debian, install the Linux dependencies used by the CI workflow:

sudo apt-get update
sudo apt-get install -y \
  build-essential pkg-config libgtk-3-dev libwebkit2gtk-4.1-dev \
  libjavascriptcoregtk-4.1-dev libsoup-3.0-dev libappindicator3-dev \
  librsvg2-dev patchelf

Clone your fork and create a focused branch.

git clone https://github.com/<your-account>/RustTextAdventure.git
cd RustTextAdventure
git checkout -b fix/descriptive-name

The Rust application lives in src-tauri/; the static frontend lives in ui/. Read docs/API.md before changing any Tauri command or its JSON contract.

3. Run and verify locally

The mandatory quality gate is intentionally the same as continuous integration.

cargo fmt --all -- --check
cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings
cargo build --workspace
node --check ui/js/app.js

Run these commands from the repository root. The unit tests cover Engine initialization, state retrieval, configuration, autocomplete, command parsing, locked paths, item pickup, and command aliases. Add a regression test whenever a bug could return.

Command Purpose
cargo fmt --all -- --check Verifies canonical Rust formatting without modifying files
cargo test --workspace Runs the unit suite, including src-tauri/src/game/tests.rs
cargo clippy --workspace --all-targets -- -D warnings Treats static-analysis warnings as failures
cargo build --workspace Confirms the native Tauri backend builds in the local environment
node --check ui/js/app.js Catches JavaScript syntax errors without launching the app

4. Repository map

Path Responsibility
src-tauri/src/main.rs Tauri command registration and managed GameState
src-tauri/src/game/engine.rs Session lifecycle, response construction, saves, configuration, achievements
src-tauri/src/game/commands.rs Parser and game command behavior
src-tauri/src/game/world.rs World, rooms, exits, and map data
src-tauri/src/game/items.rs / puzzles.rs / story.rs Content definitions and narrative rules
src-tauri/src/game/tests.rs Unit tests for Engine and command contracts
ui/js/app.js Frontend state rendering and Tauri invoke() consumers
ui/css/style.css UI styles, themes, accessibility-related presentation
docs/API.md Supported Tauri command contract
docs/ Product, validation, release-marketing, and architecture documents
.github/workflows/ CI and tag-based release automation

5. Coding conventions

Rust code must be formatted with rustfmt and pass Clippy with warnings denied. Prefer explicit state transitions over hidden side effects. Keep GameEngine tests deterministic: do not assert wall-clock timestamps, filesystem paths, or random output unless the test owns the fixture.

For frontend code, use async/await around invoke(), handle both a rejected Promise and a CommandResult whose success is false, and do not call initialize_game after a successful load_game. That would reset the restored session. Use get_game_state to render a loaded game.

For game content, preserve stable IDs. An item ID, room ID, puzzle ID, flag, or achievement ID that has already entered saves or command logic should not be renamed casually. If a rename is necessary, describe its migration effect in the pull request and CHANGELOG.

6. Tests and regression coverage

Every behavioral change should add or update a test. Favor a concise arrange–act–assert structure. Examples of good coverage include these scenarios:

  • a player cannot cross a locked exit without its required item;
  • taking an item moves it from the room into inventory;
  • a successful load is rendered with get_game_state rather than a reset;
  • an unknown command produces an error message without corrupting state;
  • changed configuration is returned unchanged through get_config.

Avoid asserting full narrative paragraphs unless the text itself is the feature under review. Prefer stable semantic checks, such as message type, room ID, item ownership, flag state, score, and puzzle state.

7. Issues and pull requests

Before writing code, search existing issues and use the provided player-feedback form for playtest observations. Open a regular issue for a focused implementation proposal when no existing issue covers it.

A pull request should include a clear summary, a linked issue when applicable, the tests run, and any user-facing screenshots or GIFs for UI changes. Keep unrelated formatting or refactors out of the same PR.

## Summary
- What user or contributor problem does this solve?
- Which engine, command, UI, or documentation contract changed?

## Validation
- [ ] cargo fmt --all -- --check
- [ ] cargo test --workspace
- [ ] cargo clippy --workspace --all-targets -- -D warnings
- [ ] cargo build --workspace
- [ ] node --check ui/js/app.js (if UI changed)

## Risk and rollout
- Save compatibility considered
- API.md updated (if Tauri command contract changed)
- CHANGELOG updated (if user-visible)

Maintainers should aim to acknowledge a complete contribution within three business days. Review comments should be specific, respectful, and centered on correctness, player experience, security, compatibility, or maintainability.

8. Commits, releases, and attribution

Use short imperative commit subjects that describe the change, for example test: cover locked-path behavior, fix: preserve state after load, or docs: document Tauri commands. A release tag is created only by a maintainer after the quality workflow passes. Contributors must not add tokens, signing keys, publishing credentials, or third-party private configuration to the repository.

Changes that affect a released binary should update CHANGELOG.md in the same PR. Changes that affect community acquisition or release messaging should also review docs/GITHUB_RELEASE_MARKETING_PLAN_FA.md.

9. Security and responsible disclosure

Do not publish an exploit, credential, or sensitive user data in a public issue. Use GitHub's private security-advisory mechanism when available, or contact the repository owner privately through their GitHub profile. Include a minimal reproduction, affected version, impact, and a safe mitigation if known.

References