🔧 Tool Setup Troubleshooting Guide

Use this page if something is not working.
Each section is independent — jump directly to the area you are stuck.

flowchart TD
    %% GitHub Sources
    subgraph GitHub_Pages[GitHub: Open-Coding-Society/pages]
        A[Repo: pages]:::repo
    end

    subgraph GitHub_Template[GitHub: Open-Coding-Society/student]
        T[Template Repo: student]:::repo
    end

    subgraph GitHub_Student[GitHub: jm1021/student]
        B[Repo: student]:::repo
    end

    %% Local Computer
    subgraph Local[Local Computer]
        subgraph opencs_dir[opencs/ directory]
            C[pages/]:::local
            Ccmd[VSCode Prep<br/><br/>./scripts/venv.sh<br/>source venv/bin/activate<br/>code .]:::cmd
        end
        subgraph user_dir[jm1021/ directory]
            D[student/]:::local
            Dcmd[VSCode Prep<br/><br/>./scripts/venv.sh<br/>source venv/bin/activate<br/>code .]:::cmd
        end
    end

    %% Arrows: cloning
    A -.->|clone/pull only| C
    B <--> |clone, pull & push| D

    %% Arrows: template relationship
    T -.->|template→created| B

    %% Arrows: commands
    C --> Ccmd
    D <--> Dcmd

GitHub Commit / Config Recovery

Use these commands if git commit is failing

✅ Expectation
You have a GitHub username + email

git config --list` # shows your GitHub username + email.

❌ If not personalized, run to match your credentials:

git config --global user.name "jm1021"        # change to your GitHub ID
git config --global user.email "jm1021@gmail.com"  # change to your Email

Or run script that does the same thing from your project directory

./scripts/activate.sh # help setup git config options

Directory + Clone Recovery

✅ Expectation: Project directory is setup correctly

You can cd into your personal directory, and an ls shows your repo folder (ex: student).

  • In VSCode open this file (tool_setup-trouble.ipynb), run the script with comment “Check for presence of repo and virtual environment”.
  • Or step through commands in terminal to aid in your comprehension.
cd ~/jm1021 # change jm1021 to your user directory name

❌ If cd fails, run:

mkdir ~/jm1021
cd ~/jm1021

Check for repo folder

ls # lshould show "student"

❌ If missing, run:

git clone https://github.com/jm1021/student.git # change to personal location of repo

Move into repo folder

cd ~/jm1021/student
ls # see listing of project files

❌ If no directory or no file list, consider gap and discuss it with team member, then TA, and then Instructor

%%script bash

# Location of student repo, change to match your personal setup
repoLocation=~/jm1021/student

# Check for presence of repo and virtual environment 
commands=(
    
  "ls --color=none -a ${repoLocation}" 
  "ls --color=none ${repoLocation}/venv/bin/activate" 
)

for cmd in "${commands[@]}"; do
  echo "### Command: $cmd"
  bash -c "$cmd"
done

Virtual Environment Recovery

✅ Expectation Your terminal prompt shows (venv) prefix.

Run Vitual Environment

cd ~/jm1021/student
source venv/bin/activate

❌ If it fails

./scripts/venv.sh
source venv/bin/activate

VSCode Launch and Memories

✅ Satisfying the pre-requisites

  • In project directory of your repo pwd
  • Sourcing virtual environment source venv/bin/activate
  • Ensure your terminal prompt shows the active virtual environment (venv).

You are now ready to load VSCode and build a proper memory to open your project.

code .

✅ Verify VSCode launch

  • Terminal and presence of (venv) prompt
  • Open your Jokes IPYNB notebook and select the Python kernel with the venv prefix.

❌ If you fail verification

You may have opened your repo project without activating the proper (venv) environment.

Check the Recent listings. If there are entries that look incorrect or outdated (bad memories), remove them all.

  • Shift-Cmd-P (Mac) or Shift-Ctl-P (Windows, KASM)
  • type: Clear Recently Open – select and confirm
  • close VSCode
  • Repeat VSCode Launch and Memories

Version Checks

✅ Expectation: Version output for all tools

In VSCode open this file (tool_setup-trouble.ipynb), run the script with comment “Version and configuration checks”.

  • Output is expected for each ### Command
  • Version may be slightly different, but ask if you are not sure
  • Java and IJava kernels are required for CSA only

❌ If anything fails

Best course of action is to run the specific OS specific activate scripts from opencs/pages project

WSL or Linux Users: Ubuntu, Kali, or Mint

./scripts/activate_ubuntu.sh # ubuntu script works for all 3 variants, as they use same apt package manager

MacOS users

./scripts/activate_macos.sh # macos

Problems with git config

./scripts/activate.sh # help setup git config options

%%script bash

# Version and configuration checks 
commands=(
  "python --version" 
  "pip --version" 
  "ruby -v" 
  "bundle -v" 
  "gem -v" 
  "jupyter --version" 
  "jupyter kernelspec list" 
  "git config --global user.name" 
  "git config --global user.email"
)

for cmd in "${commands[@]}"; do
  echo "### Command: $cmd"
  bash -c "$cmd"
done

### Command: python --version
Python 3.14.0
### Command: pip --version
pip 25.3 from /Users/johnmortensen/opencs/pages/venv/lib/python3.14/site-packages/pip (python 3.14)
### Command: ruby -v
ruby 3.4.7 (2025-10-08 revision 7a5688e2a2) +PRISM [arm64-darwin25]
### Command: bundle -v
Bundler version 2.7.1
### Command: gem -v
3.7.2
### Command: jupyter --version
Selected Jupyter core packages...
IPython          : 9.7.0
ipykernel        : 7.1.0
ipywidgets       : not installed
jupyter_client   : 8.6.3
jupyter_core     : 5.9.1
jupyter_server   : 2.17.0
jupyterlab       : 4.5.0
nbclient         : 0.10.2
nbconvert        : 7.16.6
nbformat         : 5.10.4
notebook         : 7.5.0
qtconsole        : not installed
traitlets        : 5.14.3
### Command: jupyter kernelspec list
Available kernels:
  java           /Users/johnmortensen/Library/Jupyter/kernels/java
  jbang-ijava    /Users/johnmortensen/Library/Jupyter/kernels/jbang-ijava
  python3        /Users/johnmortensen/opencs/pages/venv/share/jupyter/kernels/python3
### Command: git config --global user.name
jm1021
### Command: git config --global user.email
jmort1021@gmail.com