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.
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.
Development Environment
Pre-requisites
Install Node.js. This allows you to run JavaScript on your computer (outside of a browser).
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-widows
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. We will be using the latest LTS version, 20.10.0, lts/iron.
Install pnpm. This is our package manager of choice for this project.
It's responsible for installing, uninstalling, and keeping track of the app's dependencies.
Developing
Clone the AntAlmanac repository or your fork.
Navigate to the root directory and install the dependencies.
Start the development server for the frontend.
or
View the local website at http://localhost:5173. As you make changes to the React application, those changes will be automatically reflected on the local website.
This is all that is required to develop the frontend project locally.
But I also want to work with the backend locally...
Typically, you won't need to start the backend server locally because an active development server is available for usage.
However, if you would like to start both the frontend and the backend locally,
you can run pnpm start from the project root.
Non-Privileged
When developing as a non-privileged member, the environment variables won't reflect real credentials to resources such as the database.
The backend should still work, but with limited functionality. Please request credentials from a project lead if you need them.
Ensure that you're in the backend project. i.e. cd apps/backend from
the project root.
.env.sample to .env.pnpm start.Privileged
ICSSC Project Committee Members can be given .env files with real credentials upon request.
These can be used to access real resources such as DynamoDB, MapBox, etc.
Remove any .env.* files in the project root, and insert the .env you were given.
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-widows
A more convenient, but less secure way to resolve this is to run the command with admin privileges, e.g with sudo.
The React website doesn't seem to load at all
Try disabling your adblocker.
I need the env variables for the backend!
An example .env.sample is provided and can be used by renaming it to .env
If you need real credentials to access the database or private resources,
please contact a project lead.