Skip to content

Latest commit

 

History

History
163 lines (107 loc) · 9.31 KB

CONTRIBUTING_ADVANCED.md

File metadata and controls

163 lines (107 loc) · 9.31 KB
Raw

Contributing - Advanced

Table of Contents

Prerequisites

This contribution guide is for cases in which you need to test the functionality of your changes, or if you need to take screenshots of your changes. You will need a computer with a stable internet connection, a text editor, Git, and NodeJS with version 18.19.1. There are some additional requirements depending on what you're looking to contribute, such as Firebase for authentication, and Mongo and Docker for the backend. Read the below sections to understand how to set up each of these tools.

Git

Warning

If you are on Windows, run git config --global core.autocrlf false before cloning this repo to prevent CRLF errors.

Git is optional but we recommend you utilize it. Monkeytype uses the Git source control management (SCM) system for its version control. Assuming you don't have experience typing commands in the command line, we suggest installing Sourcetree. You will be able to utilize the power of Git without needing to remember any cryptic commands. Using a Git client such as Sourcetree won't give you access to the full functionality of Git, but provides an easy-to-understand graphical user interface (GUI). Once you have downloaded Sourcetree, run the installer. While installing Sourcetree, keep your eyes peeled for the option to also install Git with Sourcetree. This is the option you will need to look for in order to install Git. Make sure to click yes in the installer to install Git with Sourcetree.

NodeJS and NPM

Currently, the project is using version 18.19.1 LTS.

If you use nvm (if you use Windows, use nvm-windows) then you can run nvm install and nvm use (you might need to specify the exact version eg: nvm install 18.19.1 then nvm use 18.19.1) to use the version of Node.js in the .nvmrc file.

Alternatively, you can navigate to the NodeJS website to download it from there.

Docker (Recommended but Optional)

You can use docker to run the frontend and backend. This will take care of OS-specific problems but might be a bit more resource-intensive. You can download it from the Docker website.

Firebase (optional)

The account system will not let you create an account without a Firebase project. You can skip this if you don't think you will need it (you can always set it up later)

  1. Create a Firebase account if you already haven't done so.

  2. Create a new Firebase project.

    • The project name doesn't matter, but the name monkeytype would be preferred.
    • Google Analytics is not necessary.

  3. Enable Firebase Authentication

    • In the Firebase console, go to Build > Authentication > Sign-in method
    • Click on Email/Password, enable it, and save
    • Click on Google, add a support email, and save

  4. Generate a Firebase Admin private key (optional, only needed if you want to work on the backend)

    • In your Firebase console, go to Project Settings > Service Accounts
    • Click "Generate New Private Key"
    • Save as serviceAccountKey.json inside the backend/src/credentials/ directory.

  5. Run npm install -g firebase-tools to install the Firebase Command Line Interface.

  6. Run firebase login on your terminal to log in to the same Google account you just used to create the project.

  7. Within the frontend directory, duplicate .firebaserc_example, rename the new file to .firebaserc and change the project name to the firebase project id you just created.

    • Run firebase projects:list to find your firebase project ID.
    • If .firebaserc_example does not exist after cloning, create your own with:
     {
     "projects": {
         "default": "your-firebase-project-id"
     }
 }

Config file

Within the frontend/src/ts/constants directory, duplicate firebase-config-example.ts, rename it to firebase-config.ts

  • If you skipped the Firebase step, you can leave the fields blank
  • Otherwise:
    1. Navigate to Project Settings > General > Your apps
    2. If there are no apps in your project, create a new web app
    3. In the SDK setup and configuration section, select npm
    4. The Firebase config will be visible below
    5. Paste the config into firebase-config.ts
    6. Ensure there is an export statement before const firebaseConfig

If you want to access the frontend from other machines on your network create a file frontend/.env with this content:

BACKEND_URL="http://<Your IP>:5005"

Databases (optional if running frontend only)

Follow these steps if you want to work on anything involving the database/account system. Otherwise, you can skip this section.

  1. Inside the backend folder, copy example.env to .env in the same directory.

  2. Setup the database server

Manual Docker (recommended)
  1. Install MongoDB Community Edition
  2. Install Redis
  3. Make sure both are running
  1. Install Docker on your machine
  2. Run npm run docker-db-only from the ./backend directory
  1. (Optional) Install MongoDB-compass. This tool can be used to see and manipulate your database visually.
    • To connect, type mongodb://localhost:27017 in the connection string box and press connect. The Monkeytype database will be created and shown after the server is started.

Building and Running Monkeytype

Its time to run Monkeytype. Just like with the databases, you can run the frontend and backend manually or with Docker.

Dependencies (if running manually)

Run npm run install-all in the project root to install all dependencies.

  • If you are on Windows, use npm run install-windows.
  • If neither works, you will have to run npm install in root, frontend, and backend directories.

Both Frontend and Backend

Manual:

npm run dev

Backend only

Manual Docker
cd backend && npm run dev cd backend && npm run docker

Frontend only

Manual Docker
cd frontend && npm run dev cd frontend && npm run docker

These commands will start a local development website on port 3000 and a local development server on port 5005. They will automatically rebuild the website/server when you make changes in the src/ directory. Use Ctrl+C to stop them.

Note

Rebuilding doesn't happen instantaneously and depends on your machine, so be patient for changes to appear.

If you are on a UNIX system and you get a spawn error, run npm with sudo.

Standards and Guidelines

Code style is enforced by Prettier, which automatically runs every time you make a commit.

For guidelines on commit messages, adding themes, languages, or quotes, please refer to CONTRIBUTING.md. Following these guidelines will increase the chances of getting your change accepted.

Questions

If you have any questions, comments, concerns, or problems let me know on GitHub, Discord in the #development channel, or ask a question on Monkeytype's GitHub discussions and a contributor will be happy to assist you.