Skip to content
OpenMarch

Contributing

Get in here and contribute to OpenMarch! Learn our stack and codebase here.

We’d reccommend to take a look at all of our tasks, and pick some you’d like to work on. The ones with good first issue and help wanted tags are good for getting started.

Feel free to ask questions in the Discord if you’re having problems with anything.

Stack
Discord Go to #developers for support!

Running the Dev Environment

  1. Download & install Node.js
  2. Download the code via git from the main branch (if you’re contributing, make a fork and clone your own repo): git clone https://github.com/OpenMarch/OpenMarch.git
    • You might need to download git for this. You can also use other methods like the GitHub CLI
  3. Install dependencies: npm install (may take a while)
    • You might get a bunch of scary npm errors after installing. If running the app doesn’t work after, follow these steps to fix it.
  4. Run the dev environment: npm run dev
    • If you see a bunch of errors, you may need to run npm run app:prepare first. More on this in the running tests section

Codebase Structure

Our simplified directory structure:

  • /electron - The “main” process, the backend of the app, with database and system functionality
    • /database
    • /main
    • /preload - Preload script for IPC
  • /src - the “renderer” process, this is our react frontend.
    • /components - In here you find all the components of OpenMarch, the sidebars, titlebar, dialogs, UI component primitives. All of them are in their subfolder.
    • /context - React Context for the app of some sort of state/value
    • /global - Classes, objects and functions for various items in the app, such as Page, Marcher, MarcherShape, etc.
    • /stores - Global stores for certain items and actions, such as the list of Pages and Marchers
    • App.tsx - the main app file

Most of the directories like stores, context, database also have a __test__ directory. These are Vitest or Playwright tests, which test the functionalites of certain things. Tests are important, please write them!

Running Tests

Since Electron has to rebuild better-sqlite3 (the package used to interact with the database), we must follow a few steps when transitioning between running automated tests and running the app.

Prepare for testing

These steps only apply for tests involving database interactions. You don’t need to rebuild any packages if you’re only testing frontend components. If you don’t, though, the entire test suite will not pass.

For frontend specific tests, ignore the steps below and just run npm run test.

Using the Vitest extension in VSCode is also handy.

  1. Close the app if it’s running

  2. Rebuild the better-sqlite3 package

    Terminal window
    npm run test:prepare
    • This will rebuild better-sqlite3 to run on the same version of Node.js that the rest of the packages are on

  3. If the tests didn’t start, run them again

    Terminal window
    npm run test

  4. You can see other test scripts in the package.json

Running the app after testing

Since we rebuilt better-sqlite3 with npm, we must rebuild it so that it can run in our Electron main process.

Also do this if you ever see this error. It indicates that better-sqlite3 has not been rebuilt with the same version of Node.js as the Electron main process:

Failed to connect to database:
PLEASE RUN 'node_modules/.bin/electron-rebuild -f -w better-sqlite3' to resolve this

  1. Stop any tests if they are running.

  2. Rebuild better-sqlite3 for Electron

    Terminal window
    npm run app:prepare
    • This will rebuild better-sqlite3 to run on the same version of Node.js that the Electron main process is on

  3. The app should launch on its own, but if it doesn’t you can run npm run dev to launch it.