Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
165 lines (125 loc) · 6.17 KB

CONTRIBUTING.md

File metadata and controls

165 lines (125 loc) · 6.17 KB
Raw

Contributing

Thanks for wanting to work on Vortex. Before you start, there's one thing we need to be upfront about.

Important

We can only take small pull requests at the moment.

Vortex is going through large foundational changes, and we don't have the review capacity to take on big contributions alongside that work. If you send us a large PR right now, it will most likely sit unreviewed until it no longer applies to the code underneath it, and we'd have to close it. You'd have spent real time on something we couldn't merge, which is why we'd rather tell you here than in a closed PR later.

This is about our capacity, not about the quality of what you're offering. We are hiring, and it will change.

What counts as small

As a rough guide, a PR we can review without a conversation first is under 400 changed lines across 10 files or fewer, ignoring lockfiles, generated files, and mass renames.

Those aren't hard limits. A 500-line change that's one self-contained fix with tests is fine. A 200-line change touching six extensions probably isn't, because the review cost is in the blast radius, not the line count.

If your change is bigger than that, or spans several extensions, open a feature request or ask on Discord before you write it and wait for a maintainer to agree on the approach. A short conversation up front saves you from writing something we can't merge.

Pull requests

  • One logical change per PR. If the description needs the word "and", it's probably two PRs.
  • Link the issue it fixes.
  • Say what you tested and on which platform.
  • Run pnpm run verify before you open it. That covers formatting, lint, typecheck, build and tests.

Pull requests that conflict with work already planned or in progress, that don't fit the architecture, or that are too big for us to review, get closed. That's not a judgement on the code.

AI-assisted contributions

Use whatever tools you like. The requirement is the same either way: you are the author, and you need to understand every line you submit.

In practice that means you can explain why the change is written the way it is, you've run it, and you've read the diff. If a reviewer asks about a decision in your PR, "that's what the model produced" isn't an answer.

We close large machine-generated PRs without detailed review. We don't have the capacity to audit thousands of lines nobody on either side has read, and the size rule above applies regardless of how the code was written.

Recommended editor: VS Code with workspace extensions. You will be prompted to install them when you first open the repo.

Requirements

Before you start, make sure you have:

Setup

  1. Install distro-specific prerequisites:

  2. Continue with Shared Setup.

Developing

After you have finished the setup steps:

  1. pnpm run build
  2. pnpm run start

A pre-commit hook runs oxfmt over every staged file, markdown included, so expect your formatting to be rewritten. Running pnpm run format first makes the hook a no-op. The hook can also trigger a dependency install mid-commit, so a commit sometimes takes about 30 seconds and prints install output.

Hot reload (pnpm run dev)

For iterating on renderer (UI) code, pnpm run dev starts Vortex with hot module replacement instead of the build/start cycle:

  • Component (.tsx) edits hot-swap in place via react-refresh — React and Redux state are preserved, no reload.
  • Edits that can't be hot-applied (reducers, utils, extension index.ts init code) automatically trigger a clean window reload.
  • Tailwind class changes rebuild tailwind-v4.css and swap the stylesheet in place, without a reload.
  • Not covered: main-process (src/main), preload, and @vortex/shared changes still need a restart of pnpm run dev; the dynamic extensions in extensions/ and extensions/games/ still require an app relaunch.

Debugging

VS Code

  • F5 debugs both main and renderer processes
  • Build first by running pnpm run build before debugging

See docs/DEBUGGING-GUIDE.md for detailed debugging instructions.

Packaging

To build a Windows installer locally (unsigned, for testing production behavior), run pnpm package:nosign from the repo root; the output lands in dist/. Signed installers are produced by CI only.

FAQ

When will my changes be added to the stable release?

See docs/branching-and-release-strategy.md for more information.

Further Reading