GeoUIUC

CS 124H · Fall 2026 · MP Codebase

A GeoGuessr-style game for campus. You're dropped into a Google Street View spot around UIUC and have to guess where you are on the map.

Built by a CS 124H team in Fall 2025 with Next.js (React) website, Firebase (Google sign-in and a database), and Google Maps.

Your job in this MP: you're joining a project someone else wrote, just like starting a new job. Read the code, get it running, then fix, improve, or change something and submit it as a pull request. Bugs and rough edges are expected. Finding them is part of the work. Docs/RUN.md has deeper technical notes and known issues.

How to read the commands: text in grey boxes like git status is something you type into a terminal (macOS: the Terminal app; Windows: PowerShell; Linux: your terminal), then press Enter. Anything after a # is a note for you, not part of the command. Replace words in CAPITALS, like YOUR-USERNAME, with your own value.

1. One-time setup

You already have a GitHub account and Git set up. Install what this project needs (once per computer):

Node.js (the LTS version, 20 or newer): https://nodejs.org Check it worked: node --version should print v20 or higher.

2. Get your own copy of the code

You can't change the course's copy directly, so you make your own copy called a fork, then download it to your computer (clone).

a. Fork: at the top right of this page, click Fork → keep Owner as your username → click Create fork. You now have github.com/YOUR-USERNAME/FA26-MP-Codebases-GeoUIUC.

b. Clone your fork into a folder on your computer:

cd ~/Documents          # or wherever you keep your projects
git clone https://github.com/YOUR-USERNAME/FA26-MP-Codebases-GeoUIUC.git
cd FA26-MP-Codebases-GeoUIUC

c. Connect the course repo too, so you can get updates later if staff change something:

git remote add upstream https://github.com/CS196Illinois/FA26-MP-Codebases-GeoUIUC.git

Every command from here on is run inside this FA26-MP-Codebases-GeoUIUC folder. To open it in VS Code: code .

3. Add the config files

GeoUIUC needs one config file from PrairieLearn: GeoUIUC-config.env. It holds the Firebase (login and database) and Google Maps settings. It is not in this repo on purpose.

Download GeoUIUC-config.env from PrairieLearn into your Downloads folder.

In your terminal, inside the project folder, copy it into place:

macOS / Linux

cp ~/Downloads/GeoUIUC-config.env Frontend/.env.local

Windows (PowerShell)

Copy-Item $HOME\Downloads\GeoUIUC-config.env Frontend\.env.local

It must be named exactly .env.local inside Frontend/, because that's the name Next.js looks for. The name starts with a dot, so your file browser may hide it. That's normal.

4. Run the project

Make sure it works before you change anything, so you know any later problem came from your change.

cd Frontend
npm ci          # installs the libraries the project uses (first time only, takes a minute)
npm run dev     # starts the website

Open http://localhost:3000 in your browser. Click Login with Google and play a round.

To stop the website, click the terminal and press Ctrl + C. Next time you only need cd Frontend and npm run dev.

5. Make your changes

a. Make a branch. A branch is a separate line of work, so your changes stay apart from the original code. Name it after what you're doing:

git switch -c fix-profile-crash      # use your own short name, no spaces

b. Edit the code in your editor. Save often, and re-run the project to check your work.

c. See what you changed:

git status        # lists changed files
git diff          # shows the exact lines you changed

d. Save a snapshot (commit). Add the files you changed, then commit with a short message that says what you did:

git add PATH/TO/FILE1 PATH/TO/FILE2     # or: git add .   (adds everything listed by git status)
git commit -m "Fix crash on profile page when not logged in"

Commit as often as you like. Small commits with clear messages are better than one huge one.

e. Upload your branch to your fork (push):

git push -u origin fix-profile-crash   # first push of a new branch
git push                               # every push after that

6. Submit a pull request

A pull request (PR) asks the course repo to look at your changes. It's how you submit.

Open your fork on GitHub: github.com/YOUR-USERNAME/FA26-MP-Codebases-GeoUIUC.
Click the yellow Compare & pull request button. If you don't see it, click Contribute → Open pull request.
Check the top bar reads: base repository: CS196Illinois/FA26-MP-Codebases-GeoUIUC · base: main ← head repository: YOUR-USERNAME/FA26-MP-Codebases-GeoUIUC · compare: your-branch
Give it a clear title, e.g. "Fix crash on profile page when not logged in".
Fill in the description. A template appears automatically. Write your answers outside the  comments. These parts are required:
- Name and NetID
- What did you change?
- Why?
- How did you test it?
- Checklist: tick both boxes (change [ ] to [x])
Screenshots is optional, but helpful if you changed anything visible.
Click Create pull request.

An automatic check then runs. Scroll down after a few seconds:

✅ "PR checklist complete": you're done. Your PR is submitted.
❌ a comment listing problems: fix each one. To edit the description, click ··· at the top right of your first comment, then Edit. The check re-runs when you save.

Staff grade PRs with a passing check. Your PR won't be merged into the course repo. That's expected, because everyone starts from the same original code.

7. Update your pull request

Want to change something after submitting? Just commit and push to the same branch. The PR updates automatically:

git add .
git commit -m "Handle the empty-list case too"
git push

Don't open a second PR for the same work.

8. Troubleshooting

git push says "Permission denied" or "403". You cloned the course repo instead of your fork. Fix it without losing your work:

Make your fork on GitHub if you haven't yet (section 2a).
Point your copy at your fork and push:

git remote rename origin upstream
git remote add origin https://github.com/YOUR-USERNAME/FA26-MP-Codebases-GeoUIUC.git
git push -u origin HEAD

"command not found" (node, python3.12, flutter…). The tool isn't installed, or the terminal was open before you installed it. Close the terminal, open a new one, and try again. If it still fails, reinstall from section 1.

The check says my PR includes a secret file.

git rm --cached .env          # use the file name from the bot's comment
git commit -m "Remove secret file"
git push

--cached removes it from Git but keeps it on your computer.

I'm on the wrong branch / lost track of where I am. git status shows your current branch. git branch lists all branches. git switch BRANCH-NAME moves to another one.

I want to throw away my changes to one file. git restore PATH/TO/FILE puts it back to your last commit. This can't be undone.

The course repo got updated and I want those changes.

git pull upstream main

Something else? Copy the full error message and ask on the course forum or in office hours. Error messages are the most useful clue.

9. Words you'll see

Word	Meaning
Repository (repo)	A project folder whose full history Git tracks.
Fork	Your own copy of someone else's repo on GitHub.
Clone	Downloading a repo from GitHub to your computer.
Branch	A separate line of work inside a repo. `main` is the original.
Commit	A saved snapshot of your changes, with a message.
Push	Uploading your commits from your computer to GitHub.
Pull request (PR)	A request asking a repo's owners to review your changes.
`origin`	Git's nickname for your fork.
`upstream`	Git's nickname for the course repo you forked from.
`.env` file	A file of settings and secret keys. It's never committed.

Original team (Fall 2025)

Group 3

Group Name: Geo-UIUC (temporary)

MVP Link

Team Members: kxhu2, jcngo2, ags15, manuel9, ezhen11, neilad2, wr6

Project Manager: wllei2

Workflow:

Before starting:
- Ensure you're on the right branch for the feature you're working on with git branch. If not, use git checkout to switch to the right one.
- git pull origin master, if relevant changes have been merged into the master branch since last work session
- git pull
Code away!
When done:
- git add .
- git commit -m "<Description of what you added>"
- git push

Name		Name	Last commit message	Last commit date
.github		.github
.history/Frontend/src/app/game		.history/Frontend/src/app/game
Docs		Docs
Firebase		Firebase
Frontend		Frontend
Project		Project
Research		Research
.gitignore		.gitignore
README.md		README.md
firestore.rules		firestore.rules
package-lock.json		package-lock.json
package.json		package.json

Navigation Menu

Repository navigation

About

Repository files navigation

GeoUIUC

Contents

1. One-time setup

2. Get your own copy of the code

3. Add the config files

4. Run the project

5. Make your changes

6. Submit a pull request

7. Update your pull request

8. Troubleshooting

9. Words you'll see

Original team (Fall 2025)

Group 3

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

GeoUIUC

Contents

1. One-time setup

2. Get your own copy of the code

3. Add the config files

4. Run the project

5. Make your changes

6. Submit a pull request

7. Update your pull request

8. Troubleshooting

9. Words you'll see

Original team (Fall 2025)

Group 3

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages