Development workflow

Engineering principles

When making trade-offs, prioritize:

1. Correctness – simulation behavior must accurately reflect verified reference behavior.
2. Simplicity – choose the simplest complete solution over complex abstractions.
3. Maintainability – clear data flow and explicit ownership beat clever or hidden mechanisms.
4. Consistency – follow established crate conventions and standard Rust idioms.
5. Minimal churn – keep diffs focused on the task at hand. Avoid formatting or refactoring untouched code.

AI-assisted code standards

AI tools may assist with development, but generated code receives no lower review standard:

• Every line of submitted code must be understood, verified, and defended by the PR author.
• Speculative AI code dumps, unreviewed vibe-coded refactors, and phantom abstractions will be rejected during triage.
• Treat generated code as an untrusted draft: eliminate boilerplate, verify assumptions against OMSI 2.2.032 reference behavior, and write focused regression tests.

Branching model

neoOMSI uses a trunk-based workflow. main is the sole permanent integration branch.

main
├── feat/...         (new engine capabilities)
├── fix/...          (bug fixes and regressions)
├── parity/...       (verified compatibility improvements)
├── refactor/...     (simplifications preserving behavior)
├── perf/...         (performance optimizations)
├── docs/...         (documentation updates)
├── chore/...        (tooling and build infrastructure)
└── release/x.y      (temporary stabilization branches)

Working with branches

• Create focused, short-lived branches directly from main.
• Keep changes scoped to a single purpose. Avoid combining refactors with behavioral fixes.
• Delete branches upon merge.

Release branches

Temporary release/x.y branches are created only to stabilize Release Candidates. Normal development continues unhindered on main. See Releasing & versioning.

Local development and testing

For fast iteration while developing, use the development scripts detailed in Building from source:

• Windows: scripts\dev-windows.cmd (or scripts\dev-windows-release.cmd for optimized testing)
• macOS: sh scripts/dev-macos.sh

Before opening a pull request, verify that workspace checks pass:

cargo nextest run --workspace
cargo build --release

Pull requests

PR scope

• Keep pull requests small and focused on a single architectural or behavioral boundary.
• Do not mix parity fixes with unrelated cosmetic refactoring, formatting, or dependency updates.
• If a larger architectural defect is discovered, address only what is strictly necessary for the current fix and file a dedicated follow-up issue for the remainder.

Review standards

Pull requests merged into main require:

• At least two approving reviews from maintainers.
• Passing continuous integration checks.
• For parity/ changes: reference OMSI 2.2.032 evidence verifying expected behavior (see Compatibility).
• A changelog fragment for any user-visible change (see .changes/README.md).

Testing guidelines

• Bug fixes should include a unit or integration test reproducing the original issue whenever practical.
• Parsers, format deserializers, and math routines must have direct unit test coverage.
• Tests must never bundle proprietary OMSI 2 game assets. Where test fixtures are required, use synthetic mock data or optionally read from OMSI_ROOT (see Building from source).