Getting Started

Steps

Look through the issue tracker or Kanban board to find an open issue (one that hasn't been assigned to anybody) or create your own that describes the problem you want to fix.

Fork the repository or create a branch if you have the permission to do so.

Setup your development environment.

Create a draft pull request with your new branch to track your progress.

Make any desired changes, commit, and push them. Repeat until the selected issue has been addressed.

Change the pull request from draft to open. If possible, request a review from a maintainer.

Wait for your pull request to get reviewed and address any requested changes. Repeat until your pull request is approved.

Merge your pull request and your changes will appear on the live website shortly! 🥳

Additional Help

If you ever need help, feel free to ask around on our Discord server.

Install Node.js. This allows you to run JavaScript on your computer (outside of a browser). The required version is pinned in the repo's .nvmrc, so a version manager can read it automatically (nvm use / fnm use). This is best done with a version manager that allows you to easily switch between Node.js versions based on the requirements of different projects. Try using any of the following.

nvm - Node-Version-Manager.
fnm - Fast-Node-Manager.
nvm-windows

If none of those work for any reason, you can defer to your Operating System's package manager or the downloads from the official website.

Install pnpm. This is our package manager of choice for this project. The exact version we use is pinned in the root package.json (the packageManager field). It's responsible for installing, uninstalling, and keeping track of the app's dependencies.

npm install --global pnpm

Install Docker. This is required to run the local PostgreSQL database.

Docker Desktop - Available for macOS, Windows, and Linux.

Developing

Clone the AntAlmanac repository or your fork.

git clone https://github.com/icssc/AntAlmanac.git

Navigate to the root directory and install the dependencies.

cd AntAlmanac && pnpm install

Start the local PostgreSQL database using Docker Compose.

docker compose up -d --build

This starts a PostgreSQL database with the port and credentials defined in docker-compose.yml.

Set up your environment variables.

Copy apps/antalmanac/.env.example to apps/antalmanac/.env and fill in the values.
Copy packages/db/.env.example to packages/db/.env (the same DB_URL as above is fine).

Run the database migrations to set up the schema.

pnpm db:migrate

Fetch the static data (course information, term data, etc.).

cd apps/antalmanac && pnpm get-data

Start the development server.

pnpm dev

View the local website at the URL printed in your terminal (by default http://localhost:3000). As you make changes to the application, those changes will be automatically reflected on the local website with hot reloading.

What about the backend?

AntAlmanac Scheduler is a single Next.js application — the API lives inside the app as a tRPC layer, so there's no separate backend server to run. pnpm dev starts everything.

Course and instructor data comes from the Anteater API. For most local work you won't need credentials, but some features (such as the interactive map or authenticated features) require environment variables.

ICSSC Project Committee members can request .env files with real credentials (database, Mapbox, an Anteater API key, etc.) from a project lead. External contributors can develop with the example values and reach out in the Discord server if they need access to a specific resource.

Additional Commands

Database Studio — open Drizzle Studio to view and manage your local database.
pnpm db:studio
Generate Migrations — after modifying the database schema, generate a new migration.
pnpm db:generate
Run Tests — execute the test suite.
pnpm test

Testing

From the root directory, run pnpm test. Or from any directory, run pnpm -w test.

Troubleshooting

`npm i -g <package>` fails

This is usually an issue with permissions because npm is trying to install a Node package into a globally accessible location like /bin, which needs admin permissions to do so.

The best way to resolve this is to install Node via any version manager to properly handle these sorts of permissions. Here are the different version managers again.

nvm - Node-Version-Manager.
fnm - Fast-Node-Manager.
nvm-windows

A more convenient, but less secure way to resolve this is to run the command with admin privileges, e.g with sudo.

The website doesn't seem to load at all

Try disabling your adblocker or browser extensions that might interfere with local development.

I need environment variables!

Please reference the .env.example files provided. If you need production credentials to access the database or other private resources, please contact a project lead.