Skip to content

Latest commit

 

History

History
138 lines (92 loc) · 6.76 KB

CONTRIBUTING.md

File metadata and controls

138 lines (92 loc) · 6.76 KB
Raw

Quadratic Contribution Guide

Thank you for considering contributing to Quadratic, the infinite data science spreadsheet ✨

Before contributing, please respond to the issue you'd like to work on; someone on the team will get in touch to help. Alternatively, feel free to reach out to the team to get in touch and discuss contributing.

Read our Code of Conduct to keep our community approachable and respectable.

In this guide, you will get an overview of the contribution workflow from opening an issue, creating a PR, reviewing, and merging the PR.

If you have any problems getting the project to run locally, please create an issue to document the problem. See "Create an issue" below.

Quadratic is hiring

Check out our open roles ⟶ careers.quadratichq.com

Setup

  1. Install NPM
  2. Install rustup
  3. Install wasm-pack
  4. rustup target add wasm32-unknown-unknown to install the WASM toolchain
  5. Install cargo watch cargo install cargo-watch

Run Quadratic

In order to run the front-end and/or the server locally, you must have all the environment variables configured in .env.local (and quadratic-api/.env.local if you’re running a local server). You can grab the values from our team Notion page or by asking a team member.

  1. Start everything in one terminal: npm start

Run front-end locally

  1. cd quadratic-client
  2. npm i to install dependencies
  3. Configure .env.local values: touch .env.local
  4. (a) npm start to run in browser or npm run dev to run with Electron; or (b) npm run watch:front-end to run in browser with automatic wasm rebuilding

Note:

To rebuild the rust types after npm start, you need to either manually call npm run build:wasm:types, or restart the `npm start" script.

Run server locally

  1. cd quadratic-api

  2. npm i

  3. Install and configure PostgreSQL:

    1. macOS users: Install postgress.app (follow instructions on website) or brew install postgresql (instructions)
    2. Linux users:
      1. Install postgres
      2. Configure your user permissions and create the database in the psql prompt:
        • # CREATE ROLE username WITH LOGIN PASSWORD 'some_password';
        • # CREATE DATABASE "quadratic-api" WITH OWNER = username;
        • # GRANT ALL PRIVILEGES ON DATABASE "quadratic-api" TO username;
        • # ALTER ROLE username CREATEDB;

  4. Create two environment files .env.local & quadratic-api/.env.local.

    • Note: Linux users may need to call it quadratic-api/.env instead.

    • For the .env.local react app ENV variables you will need to set the following variables: VITE_AUTH0_DOMAIN VITE_AUTH0_CLIENT_ID VITE_AUTH0_AUDIENCE VITE_AUTH0_ISSUER VITE_QUADRATIC_API_URL You will need to ask your team for the appropriate values.

    • For quadratic-api/.env.local you will need to set the DATABASE_ENV to point at your local postgres db. You will also need to copy AUTH0_JWKS_URI and AUTH0_ISSUER from quadratic-api/.env_example into your local quadratic-api/.env.local api env variables.

  5. npm run prisma:migrate

Run tests (TypeScript)

  1. npm run build:wasm:nodejs to compile the Rust code
  2. npm install to install dependencies (run again when updating Rust)
  3. npm run test:all to run all tests or npm run test:unit to run just unit tests

Run tests (Rust)

  1. cd quadratic-core
  2. cargo test --workspace

Feature requests and bugs

Quadratic uses GitHub issues to track all feature requests and bugs.

Create an issue

If you have a feature request or spot a problem, search if an issue already exists. If a related issue does not exist, please open a new issue!

When reporting a bug, please provide:

  • Issue description
  • Steps to reproduce the issue
  • What's the expected result?
  • What's the actual result?
  • Additional details / screenshots

Solve an issue

Scan through our existing issues to find one that interests you. You can narrow down the search using labels as filters. See Labels for more information.

How to contribute code

  1. Fork the repository.
  2. Run Quadratic locally. See "Getting Started" above.
  3. Create a new working branch and start making your changes!
  4. Lint and format your changes using Prettier.

Pull Request

When you're finished with your changes:

  1. Create a pull request.
  2. Link your PR to the GitHub Issue link PR to issue if you are working on an Issue.
  3. Enable the checkbox to allow maintainer edits so the branch can be updated for a merge.

We review all PRs quickly, so we will give you feedback in short order!

Your PR is merged

Congratulations! 🎉🎉 Quadratic is better because of you. ✨

Once your PR is merged, contributors will be publicly visible on the GitHub Page.

How to test js.rs functions (Rust functions that call into TS)

Use #[serial] from use serial_test::serial; for the test function (this ensures that the global static TEST_ARRAY is not changed by other functions).

Any time a jsFunction is called from js.rs, the function and its args are added to the lazy_static TEST_ARRAY in js.rs. You can access the results of that via two functions:

expect_js_call(name: &str, args: String, clear: bool) - asserts whether the function with the name has the args (usually formatted as format!("{},{}", &arg1, &arg2) -- but check the js.rs for the actual format). This removes that call from the TEST_ARRAY. If clear = true then it also clears the entire TEST_ARRAY (which is needed since we don't have 100% coverage on all js.rs calls yet).`

expect_js_call_count(name: &str, count: usize, clear: bool) - asserts whether the name function was called a specific number of times. If it matches it will clear the TEST_ARRAY of those functions. If clear = true then it will also clear the entire TEST_ARRAY (for the same reason as above).