Starting a Project

The following commands are universal for all machine types, terminals, and projects. The previous installation steps ensured that all machine types have compatible tools. Follow these steps in order:

Open a Linux-supported Terminal

You are using Ubuntu, Kali, MacOS in this step.

Clone repository

Use same repo that you modified in vscode.dev.

Change the commands below to use your own organization name (not “opencs” of “jm1021”). This is your personal template repository (not “open-coding-society/student.git”).

For example, if your GitHub organization is jm1021 and your repo is **student, use:

   cd                # move to your home directory
   mkdir -p jm1021   # use your organization name here
   cd jm1021         # use your organization name here
   git clone https://github.com/jm1021/student.git   # use your organization/repo here

Prepare project prior to opening VS Code

   cd student # Move to your personal project directory
   ./scripts/venv.sh # Activate the virtual environment (observe the prompt change)
   source venv/bin/activate # Prefix (venv) in path
   bundle install # Ensure Ruby gems for GitHub Pages is installed in (venv)
   code . # Open the project in VS Code

Authenticate with GitHub

  • At some point, you may be prompted to authenticate with GitHub. Follow the dialog and instructions.

For WSL Users Only

  • Ensure that VS Code is opened in WSL. Check the bottom-left corner of the VS Code window to confirm. This is critical for success! wsl

Software Development Life Cycle (SDLC)

The development cycle involves iterative steps of running the server, making changes, testing, committing, and syncing changes to GitHub. This process ensures that your website is updated and functioning correctly both locally and on GitHub Pages.

SDLC Workflow

+-------------------+       +-------------------+       +-------------------+       +-------------------+       +-------------------+
|                   |       |                   |       |                   |       |                   |       |                   |
|   Make Server     | ----> |   Change Code     | ----> |     Commit        | ----> |      Test         | ----> |     Sync          |
|                   |       |                   |       |                   |       |                   |       |                   |
+-------------------+       +-------------------+       +-------------------+       +-------------------+       +-------------------+
        |                           |                           |                           |                           |
        v                           v                           v                           v                           v
 Start Local Server           Edit Code Files           Stage Changes Locally        Verify Local Changes        Push Changes to Cloud

Open Project and Make

All students are building a GitHub Pages website. These steps get your website running on your desktop (local or cloud).

What is make?

Think of make as a smart task helper for developers.

  • It automates commands you would normally type one by one.
  • It starts a localhost server on you machine, enabling Testing prior to Sync.
  • It reads a special file called a Makefile, which lists tasks and how to run them.

Simply run:

make

And it will do everything listed in the Makefile.

  1. Open a terminal

  2. Navigate to your project directory

  3. Activate virtual environment (venv) source venv/bin/activate

  4. Open VSCode code .

  5. Open a VSCode Terminal

  6. Type make This runs a build to a local server. Repeat this command as often as you make changes.

  7. Hover then Cmd or Ctl Click on the localhost Server Address http://localhost: … provided in the terminal output from the make command.

### Congratulations!!! An output similar to below means tool and equipment success ###
(venv) johnmortensen@Mac pages % make
Stopping server...
Stopping logging process...
Starting server with current config/Gemfile...
Server PID: 40638
appending output to nohup.out
Server started in 17 seconds
    Server address: http://localhost:4500/
Terminal logging starting, watching server for regeneration...
Server started in 0 seconds
Configuration file: /Users/johnmortensen/opencs/pages/_config.yml
            Source: /Users/johnmortensen/opencs/pages
       Destination: /Users/johnmortensen/opencs/pages/_site
 Incremental build: enabled
      Generating... 
      Remote Theme: Using theme jekyll/minima
                    done in 16.396 seconds.
 Auto-regeneration: enabled for '/Users/johnmortensen/opencs/pages'
    Server address: http://localhost:4500/

Make workflow (local build: make, make dev, make clean, make stop, make convert)

These commands are used to build and manage a localhost version of the website. The purpose of this is to verify and test code changes prior to pushing changes to GitHub Pages.

  • make: Runs the full local server with all features and document overhead.

  • make dev: Runs a minimal, faster build intended for developers actively coding. Skips heavy document processing so the server starts and regenerates quickly. Use this when you are iterating on game logic, layouts, or interactive features and want rapid feedback.

  • make clean: Stops the local server and cleans the build files. Try this after rename as it could cause duplicates in build.

  • make stop: Stops the local server. This means you will be unable to access your blog on http://localhost until you run make again.

  • make convert: Converts Jupyter Notebook files. Run this if your .ipynb files are not updating on the server; it may assist in finding the error.

Make Debug Lab — Interactive Practice

Got errors? This interactive lab covers common make errors and browser DevTools debugging scenarios. Use the Learn tab for a quick reference, then test yourself in Practice by solving errors to reveal pixel art.

Click to open the Make Debug Lab

Make & DevTools Debug Lab

Learn to resolve common make errors and use browser DevTools to debug game issues

Make Errors Terminal

Make Not Found

make: command not found
'make' is not recognized as an internal or external command

Your system does not have make installed.

Install Xcode Command Line Tools
xcode-select --install
Verify installation
make --version
Install WSL
wsl --install
Install make in WSL
sudo apt update && sudo apt install make

No Makefile Found

make: *** No targets specified and no makefile found. Stop.

Make cannot find the Makefile. You are probably in the wrong directory.

Check current directory
pwd
List files to confirm Makefile exists
ls -la
dir
Navigate to project directory
cd /path/to/project

No Rule to Make Target

make: *** No rule to make target 'sever'. Stop.

The target you specified does not exist. Check for typos.

List available targets
grep "^[a-zA-Z]" Makefile
findstr /B /R "^[a-zA-Z]" Makefile
Fix the typo in your command — or use make dev for a faster build
make server
make dev

Missing Separator

Makefile:5: *** missing separator. Stop.

Commands in Makefiles must be indented with TAB characters, not spaces.

Open Makefile and go to the indicated line
Delete any spaces at the beginning of command lines
Press TAB key once before each command

Permission Denied

make: ./script.sh: Permission denied

The script does not have execute permissions.

Add execute permission
chmod +x script.sh
Run make again

Command Not Found in Makefile

make: *** [server] Error 127
/bin/sh: python3: command not found

The Makefile is trying to run a command that is not installed.

Check if command exists
which python3
where python3
Install the missing tool
brew install python3
winget install Python.Python.3

Game / Browser DevTools Errors DevTools

When building or debugging a game in your GitHub Pages project, use browser DevTools (F12 or Cmd+Option+I) to diagnose these common issues. Run make dev for a fast local server while iterating on game code.

Collision Bug — Elements View

Player passes through wall / hitbox looks wrong in the game

The collision box does not match the visible sprite. Inspect the element to see its real size and position.

Open DevTools → Elements tab (Cmd+Option+I → Elements)
Hover over the player or wall element in the DOM — the browser highlights its bounding box on screen
Check that width, height, and position CSS match your expected hitbox dimensions
Fix the discrepancy in your CSS or JavaScript collision logic
// Example: log element bounds in console const box = player.getBoundingClientRect(); console.log(box.width, box.height, box.x, box.y);

Style Bug — CSS View

Sprite is invisible, wrong color, or in the wrong position

A style rule is overriding your intended CSS. Use the Styles panel to find the conflict.

Open DevTools → Elements → Styles panel
Select the game element — look for strikethrough rules, which means a rule is being overridden
Identify the conflicting selector with higher specificity and either increase your specificity or remove the conflict
Toggle rules on/off live in the Styles panel to test fixes before changing code
/* Example: use a more specific selector to override */ #game-canvas .player-sprite { display: block; visibility: visible; }

CORS Error — Network View

Access to fetch at 'https://api.example.com/npc-data' from origin 'http://localhost:4500' has been blocked by CORS policy

Your game is fetching data (NPC configs, maps, scores) from a server that has not allowed your origin. Check the Network tab to diagnose.

Open DevTools → Network tab, then reload or trigger the fetch
Find the failing request (shown in red) and click it to see Response Headers
Look for Access-Control-Allow-Origin — if missing or wrong, the server must add it
As a local workaround during make dev, proxy the request through your Jekyll server or use a CORS-friendly test API
// Example: catch CORS errors explicitly fetch('https://api.example.com/npc-data') .catch(err => console.error('CORS or network error:', err));

Logic Bug — Player / NPC Interaction

NPC does not react to player / interaction triggers at wrong time

The interaction condition in your game logic has a bug. Use the Console and Sources tabs to step through the code.

Open DevTools → Console — look for errors or add console.log calls inside your interaction handler
Open DevTools → Sources → find your game JS file and set a breakpoint on the interaction function
Trigger the interaction in the game — execution pauses at the breakpoint so you can inspect variable values
Check distance/overlap calculations, event listener binding, and state flags (e.g., isNearNPC)
// Example: debug interaction check function checkInteraction(player, npc) { const dist = Math.hypot(player.x - npc.x, player.y - npc.y); console.log('distance to NPC:', dist, '| threshold:', npc.triggerRadius); if (dist < npc.triggerRadius) npc.interact(); }

Debug Art Challenge

Answer error clues correctly to reveal the hidden pixel art — now with DevTools challenges!

Progress
0/21
Correct
0
Errors
0

Click a number to solve its error

Current Clue

1 - Not Found
2 - No File
3 - Typo
4 - Tab
5 - Permission
6 - Tool
7 - Collision
8 - Style
9 - CORS
10 - Logic
Click a numbered pixel above to start!
Select any pixel with a number to see its error.
Build Successful!

You have mastered make and DevTools debugging

Accuracy
0%

VSCode Commit and Sync Workflow

All students will be writing and changing code. These steps allow you to change the website, first locally and then on public location.

+-------------------+       +-------------------+       +-------------------+       +-------------------+
|                   |       |                   |       |                   |       |                   |
|   VS Code Editor  | ----> |   Local Git Repo  | ----> |   Remote GitHub   | ----> |   GitHub Pages    |
|                   |       |                   |       |                   |       |                   |
+-------------------+       +-------------------+       +-------------------+       +-------------------+
        |                           |                           |                           |
        |                           |                           |                           |
        v                           v                           v                           v
    Save Files                Commit Changes               Sync Changes                Public Website
   Local Website

Detailed SDLC Steps

The SDLC adds the important steps of Make and Test to the workflow. This ensures that you never sync code that is broken locally. This helps the developer troubleshoot errors early and as you are working.

  1. Save Files in VS Code:

    • Edit your files.
    • Save the changes (Cmd + S on Mac or Ctrl + S on Windows/Linux).
    • Verify changes on the local web server.

  2. Commit Changes in VS Code:

    • Click on the “Source Control” icon in the left sidebar.
    • Stage your changes by clicking the plus sign next to the files.
    • Enter a commit message.
    • Click the “Commit” button.

  3. Test Changes on Local Server:

    • Open Terminal.
    • Be sure the “(venv)” prefix is in the prompt.
    • Type make in the prompt (run make).
    • If you are actively developing a game or interactive feature, use make dev instead — it skips heavy document processing for a faster build cycle.
    • If successful, you will see log output in the prompt:
        Server address: http://localhost:4500/
    • If delayed open 2nd terminal using + and execute command cat \tmp\jekyl4500.log. This keeps ongoing history of logs if things are right a below, if things are wrong you will see errors.
    (venv) johnmortensen@Mac pages % cat /tmp/jekyll4500.log 
Configuration file: /Users/johnmortensen/opencs/pages/_config.yml
            Source: /Users/johnmortensen/opencs/pages
      Destination: /Users/johnmortensen/opencs/pages/_site
Incremental build: enabled
      Generating... 
      Remote Theme: Using theme jekyll/minima
                  done in 16.396 seconds.
Auto-regeneration: enabled for '/Users/johnmortensen/opencs/pages'
   Server address: http://localhost:4500/
Server running... press ctrl-c to stop.
      Regenerating: 1 file(s) changed at 2025-11-20 06:20:27
                  _posts/Foundation/B-tools_and_equipment/2025-04-15-tools_setup-vscode.md
      Remote Theme: Using theme jekyll/minima
                  ...done in 16.992685 seconds.
                     
      Regenerating: 1 file(s) changed at 2025-11-20 06:22:30
                  _posts/Foundation/B-tools_and_equipment/2025-04-15-tools_setup-vscode.md
      Remote Theme: Using theme jekyll/minima
                  ...done in 16.763741 seconds.
    • Open the localhost Server address in deskop or cloud computer browser http://localhost:4500/
    • Test your changes before you commit.
  4. Errors in terminal
    • Most likely cause is (venv) in prompt (venv) johnmortensen@Mac pages %. This will fail 100% of the time
    • If there are errors in coding the will show in terminal (with a delay/timeout) and be in log: cat /tmp/jekyll4500.log
    • Most likely error, is what you just changed!!! Easiest fix is to undo, see if it fixes things. Then try again.
  5. Regeneration messages
    • Most changes will show regeneration message in terminal after you save file.
    • If you see a message in terminal like the one below, you can test your localhost change by refreshing page you are working on.
    Regenerating: 1 file(s) changed at 2025-11-20 06:40:18
                  _posts/Foundation/B-tools_and_equipment/2025-04-15-tools_setup-vscode.md
      Remote Theme: Using theme jekyll/minima
                  ...done in 16.537365 seconds.

  6. Sync Changes to GitHub:

    • Never sync changes before you test, as this activates Actions on GitHub.
    • Click the “Sync Changes” button in the Source Control view.
    • This pushes your local commits to the remote GitHub repository.

  7. Update GitHub Pages:

    • GitHub Pages Action automatically rebuilds your site with the latest changes.
    • Visit your public website at https://.github.io/student to see the updates.
flowchart TD
    A[Run Server] --> B[Make Changes]
    B --> C[Commit]
    C --> D[Test]
    D --> E{Tests Pass?}
    E -- Yes --> F[Sync]
    E -- No  --> B

   style E fill:#FF0000
Rock Paper Scissors — Console Debugging Lesson

Debugging with
Rock Paper Scissors

Play the game by clicking the icons, or open your browser console and type commands directly.
Each lesson teaches a real debugging concept using the game.

HOW TO USE THIS LESSON

STEP 1 — OPEN CONSOLE

Press F12 (Windows) or Cmd+Opt+I (Mac), then click the Console tab.

STEP 2 — TRY BROKEN CODE

Click "▶ Run Broken" on any error card to see what the error looks like — just like a real console!

STEP 3 — AUTO-FIX IT

Hit "[*] Auto-Fix" to instantly patch the bug and watch the game play. See exactly what changed!

STEP 4 — TYPE IN CONSOLE

Try it yourself! Type playRPS("rock") in your real browser console to control the game live.

▶ LIVE GAME — CLICK TO PLAY

ROCK
PAPER
SCISSORS
Click an icon above — or type playRPS("rock") in your browser console!

LESSON 1 — WHAT IS THE CONSOLE?

The browser console lets you run JavaScript live on any page — no file editing needed. This game is already loaded, so you can control it directly from there.

  1. Press F12 (or Cmd+Option+I on Mac) to open DevTools
  2. Click the Console tab at the top
  3. Type playRPS("rock") and press Enter
  4. Watch the battle animation above respond in real time!
  5. Try rock.rotate(45) or paper.setBorder("3px solid lime") to customize images

LESSON 2 — FINDING & FIXING BUGS

Each card below shows a real bug. Click ▶ Run Broken to see the simulated error, then use [*] Auto-Fix to patch the code automatically and play — or ▶ Run Fixed to just see the correct result.

BUG #1 — MISSING QUOTES

playRPS(rock)

rock

Without quotes, JavaScript thinks rock is a variable name — but no variable called rock exists. It looks for rock as a declared variable, fails, and throws an error.

[x] BROKEN CODE
playRPS(rock)
[+] FIXED CODE
playRPS("rock")
Why? String values need quotes. Without them, JS looks for a variable called rock and throws a ReferenceError when it can't find one. Always wrap text in "quotes".
BUG #2 — INVALID INPUT

playRPS("lizard")

rock paper scissors

"lizard" isn't one of the three valid choices. The function checks your input against an allowed list and rejects anything not on it.

[x] BROKEN CODE
playRPS("lizard")
[+] FIXED CODE — use a valid choice
playRPS("scissors")
Why? The game validates your input against ["rock","paper","scissors"]. If .includes() returns false, the function rejects the call. Always pass a value that the function is designed to accept.
BUG #3 — WRONG CAPITALIZATION

playRps("paper")

paper

JavaScript is case-sensitive. playRps and playRPS are two completely different identifiers — only one of them exists.

[x] BROKEN CODE
playRps("paper")
[+] FIXED CODE
playRPS("paper")
Why? JS treats every character as meaningful — R, P, and S are uppercase in playRPS. playRps does not exist as a function, so JS throws a TypeError.

LESSON 3 — THE DEBUG PROCESS

  1. Read the error message — it pinpoints the problem (line, type, description)
  2. Check spelling & capitalization — playRPS ≠ playRps
  3. Check your inputs — strings need quotes, values must be valid
  4. Run the fix and verify in the console output
  5. Test edge cases — what happens with "ROCK", "", or 123?

CHALLENGE — WHY DOES THIS WORK?

Try this — it uses all-caps but still plays correctly:

playRPS("ROCK")
Hint: The game calls .toLowerCase() on your input before checking it. So "ROCK", "Rock", and "rock" all work. That technique is called defensive programming — making code resilient to small user mistakes.

CHECKPOINT — FIX THE BUG

The code below has an error. Type the corrected version in the box and press Run:

playRPS(scissors)

VSCode & Browser Console Debugging Workflow

All students will encounter bugs in their code. These steps help you find and fix errors using both VSCode’s built-in debugger and the browser’s developer console.

+-------------------+       +-------------------+       +-------------------+       +-------------------+
|                   |       |                   |       |                   |       |                   |
|   VS Code Editor  | ----> |  VSCode Debugger  | ----> |  Browser Console  | ----> |   Fix & Re-Test   |
|                   |       |                   |       |                   |       |                   |
+-------------------+       +-------------------+       +-------------------+       +-------------------+
        |                           |                           |                           |
        |                           |                           |                           |
        v                           v                           v                           v
   Write/Edit Code           Set Breakpoints             Inspect Errors              Commit Working Fix
                             Inspect Variables           Check Network/Logs

Detailed Debugging Steps

Debugging is part of the SDLC. Always debug locally before syncing to GitHub. Use VSCode and the browser console together to isolate and fix issues quickly.

  1. Reproduce the Bug in VSCode:

    • Run your local server (make or make dev).
    • Confirm the bug appears at http://localhost:4500/.
    • Note the exact conditions that trigger it (what page, what action, what input).

  2. Set Breakpoints in VSCode:

    • Open the file where you suspect the bug.
    • Click in the gutter (left margin) next to a line number to set a red breakpoint dot.
    • Open the Run and Debug panel (Ctrl+Shift+D / Cmd+Shift+D).
    • Click “Start Debugging” (F5) or use the play button.

  3. Inspect Variables in the Debugger:

    • When code hits a breakpoint, execution pauses.
    • Check the Variables panel on the left to see current values.
    • Hover over any variable in the editor to see its value inline.
    • Use the Watch panel to track specific expressions (e.g., myArray.length).
    • Use the Debug Console (bottom panel) to run live expressions:
    > myVariable
42
> typeof myVariable
"number"

  4. Step Through Code:

    • Step Over (F10): Run the next line without going into functions.
    • Step Into (F11): Jump inside a function call.
    • Step Out (Shift+F11): Finish current function and return to caller.
    • Continue (F5): Resume until the next breakpoint.
    Paused at line 24 → Step Over → Step Into → Inspect → Continue

  5. Open Browser Developer Console:

    • In Chrome/Edge: press F12 or right-click → Inspect → Console tab.
    • In Firefox: press F12 → Console tab.
    • Look for red error messages — these pinpoint the file and line number.
    • Use console.log() in your code to print values at key points:
    console.log("Value of x:", x);
console.log("Array contents:", myArray);

  6. Read Error Messages Carefully:

    • Most errors include a file name and line number — go there first.
    • Common error types:
    Error Type What It Means Likely Fix
    ReferenceError Variable not defined Check spelling, scope
    TypeError Wrong data type used Check variable value/type
    SyntaxError Bad code structure Check brackets, commas
    404 Not Found File/resource missing Check file path/name
    Uncaught prefix Error not handled Wrap in try/catch

  7. Use the Network Tab (for API/resource issues):

    • In DevTools, click the Network tab.
    • Refresh the page — all requests appear here.
    • Red rows = failed requests. Click them to see the status code and response.
    • Filter by XHR or Fetch to isolate API calls.

  8. Fix the Bug and Re-Test:

    • Make the smallest change that fixes the problem.
    • Save and watch for the Regeneration message in terminal.
    • Refresh http://localhost:4500/ and verify the bug is gone.
    • Remove any temporary console.log() statements before committing.

  9. Commit the Fix:

    • Only commit once the bug is confirmed fixed locally.
    • Write a clear commit message describing what was broken and how it was fixed:
    Fix: corrected undefined variable in navbar.js (line 24)
    • Then follow the standard Sync workflow — never sync broken code.
flowchart TD
    A[Bug Observed on Localhost] --> B[Set Breakpoint in VSCode]
    B --> C[Start Debugger / F5]
    C --> D[Inspect Variables & Step Through Code]
    D --> E[Open Browser Console]
    E --> F[Read Error Message + Line Number]
    F --> G{Root Cause Found?}
    G -- No --> H[Add console.log / Check Network Tab]
    H --> F
    G -- Yes --> I[Make Fix]
    I --> J[Re-Test on Localhost]
    J --> K{Bug Fixed?}
    K -- No --> B
    K -- Yes --> L[Remove debug logs]
    L --> M[Commit Fix & Sync]

    style G fill:#FF0000
    style K fill:#FF0000