Skip to content

Contributing

Jump to bottom
rebaserHEAD edited this page Jul 26, 2026 · 2 revisions

Contributing

How changes land in GRIMP, and what the CI gate expects from you. If you're building UI, read the UI Style Guide alongside this.

How changes land

Work goes through pull requests:

  1. Branch off main.
  2. Make your change, with tests where the change is testable.
  3. Open a PR. The template asks what you changed, what you ran, and walks the checklist.
  4. CI runs the Checks job: format check, typecheck, tests, and a production build. It has to go green.
  5. A maintainer reviews and merges.

main is protected: the Checks job is required and force-pushes are blocked. Merged branches are kept on the remote as a historic record, so don't delete them after merge.

Before you open a PR

Run these locally; they're exactly what CI runs:

npm run format        # Prettier writes formatting (config is in the repo)
npm run typecheck     # tsc --noEmit
npm run test          # Vitest suite
npm run build         # production build

If your change is user-facing, add a line to CHANGELOG.md under Unreleased. Internal refactors and CI plumbing don't need one.

Testing standards

Tests live next to the code in __tests__/ directories and run on Vitest. New behavior ships with tests; bug fixes ship with a test that would have caught the bug.

The parity sweep

Byte-exact round-trip against the game's own serializer is a core product promise. If you touch the importer (src/import/) or exporter (src/export/), run the sweep against a real fork's map corpus before opening the PR:

SS14_MAPS_DIR=<your-fork>/Resources/Maps npx vitest run src/__tests__/parity-sweep.test.ts

It round-trips every map in the corpus and fails on any new byte drift, import failure, or non-idempotent output. Known-justified drift is documented in the test; anything new is a regression.

Style

  • Formatting is Prettier's call, not a review topic. Run npm run format and move on.
  • UI work follows the UI Style Guide: theme tokens over hardcoded hexes, one accent color, dense flat chrome, pixel art rendered pixelated.
  • Comments must match the code they describe. If you change behavior, update the comment in the same commit.

What not to commit

No Space Station 14 game content, ever. The editor ships with zero game assets and discovers a fork's content from disk at runtime. That means no test maps, no RSI sprite sheets, no prototype YAML, not even as test fixtures. Tests that need game-shaped data construct it inline.

Issues

The backlog lives in GitHub Issues. Most open issues carry a scoping comment with grounded pointers into the code (what exists, what's missing, known gotchas), so read the comments before starting work. If you're planning something new, open an issue first so the approach can be sanity-checked before you build it.

Releases

Releases are tag-driven: pushing a v* tag builds the Windows portable .exe and Linux AppImage and assembles a draft GitHub release, with the release body pulled from that version's CHANGELOG.md section. A maintainer reviews and publishes the draft. At release time the Unreleased changelog section rolls over into the new version's entry.

Clone this wiki locally