From 0ce524952e97c4ec39fc39912ec69b193c2a25b2 Mon Sep 17 00:00:00 2001 From: sarahalsaady <148502402+salsaady@users.noreply.github.com> Date: Tue, 15 Jul 2025 21:31:53 -0400 Subject: [PATCH 1/3] add onboarding doc --- docs/ONBOARDING.md | 146 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 146 insertions(+) create mode 100644 docs/ONBOARDING.md diff --git a/docs/ONBOARDING.md b/docs/ONBOARDING.md new file mode 100644 index 0000000..f518e9a --- /dev/null +++ b/docs/ONBOARDING.md @@ -0,0 +1,146 @@ +# CuMind Development Environment Setup Guide + +This guide walks you through setting up the CuMind development environment on **macOS** and **Windows (WSL)** using GitHub, VSCode or Cursor, and `uv` for Python dependency management. + +## 1. Platform Prerequisites + +CuMind requires a Linux-based development environment. + +To achieve this on your machine: + +### On Windows: + +- Install WSL and Ubuntu by following the [official Microsoft guide](https://learn.microsoft.com/en-us/windows/wsl/install) +- Recommended: WSL 2 and Ubuntu 22.04 +- After installation, open "Ubuntu" from the Start Menu to launch your WSL terminal +- Use a code editor such as [VSCode](https://code.visualstudio.com/) or [Cursor](https://cursor.so) that supports WSL. + If you're using VSCode, install the **Remote - WSL** extension — you'll use it to open and work with the project from inside your WSL environment after cloning the repository. + - Additional resource: [VSCode: Developing in WSL](https://code.visualstudio.com/docs/remote/wsl) + +### On macOS: + +- No WSL needed — the built-in Terminal provides a compatible Unix-based environment +- Use any local code editor such as [VSCode](https://code.visualstudio.com/) or [Cursor](https://cursor.so) + +## 2. Setup Python & `uv` + +### 1. **Install Python** + +Ensure Python 3.12 or higher is installed: + +```bash +python3 --version +``` + +If not installed or the version is too old, install: + +- #### On WSL: + + Install Python and pip: + + ```bash + sudo apt update + sudo apt install python3 python3-pip + ``` + +- #### On macOS: + + Download and install the latest version from: [https://www.python.org/downloads/](https://www.python.org/downloads/) + +### 2. **Install `uv`** + +Install the Python dependency manager `uv`: + +```bash +curl -LsSf https://astral.sh/uv/install.sh | sh +``` + +Or using pip/pipx: + +```bash +pip install uv +# or +pipx install uv +``` + +More details: [uv documentation](https://astral.sh/uv/) + +## 4. Clone Repo and Setup Git Authentication + +You can clone the repo using either **SSH** or **HTTPS**. + +### Option 1: SSH (Recommended) + +1. Generate a new SSH key (if you don't have one already): + +```bash +ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519 -C "your_email@example.com" +``` + +2. Copy your public key: + +```bash +cat ~/.ssh/id_ed25519.pub +``` + +3. Add it to GitHub: + [https://github.com/settings/ssh/new](https://github.com/settings/ssh/new) + +4. Test your connection: + +```bash +ssh -T git@github.com +``` + +5. Clone the repo: + +```bash +git clone git@github.com:carletonai/CuMind.git +``` + +> If you already have an SSH key and have it registered with GitHub, skip steps 1–3. + +### Option 2: HTTPS + +Clone the repo using: + +```bash +git clone https://github.com/carletonai/CuMind.git +``` + +You’ll be prompted to enter your GitHub **username** and a **personal access token** (PAT) instead of a password. +Generate a PAT here: [https://github.com/settings/tokens](https://github.com/settings/tokens) + +## 5. Set Up and Run the Project + +Once the repo is cloned, navigate to it and install dependencies: + +```bash +cd CuMind +uv sync +``` + +Test out running a specific file to make sure your setup is working: + +`uv run python src/cartpole.py` + +To run the full application: + +`uv run python -m cumind` + +## 6. Test Your Git Setup + +Make sure you can push a new branch: + +```bash +git checkout -b YOUR-BRANCH-NAME +git push origin YOUR-BRANCH-NAME +``` + +Once confirmed, please delete the test branch: + +`git push origin --delete test-branch` + +## You’re Ready! + +You should now be able to develop and contribute to CuMind locally. If you run into issues, feel free to reach out on Discord. From 918db75c1f92964758caf856182c61116527943b Mon Sep 17 00:00:00 2001 From: sarahalsaady <148502402+salsaady@users.noreply.github.com> Date: Tue, 15 Jul 2025 22:57:13 -0400 Subject: [PATCH 2/3] update doc --- docs/ONBOARDING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/ONBOARDING.md b/docs/ONBOARDING.md index f518e9a..3659502 100644 --- a/docs/ONBOARDING.md +++ b/docs/ONBOARDING.md @@ -133,8 +133,8 @@ To run the full application: Make sure you can push a new branch: ```bash -git checkout -b YOUR-BRANCH-NAME -git push origin YOUR-BRANCH-NAME +git checkout -b test-branch +git push origin test-branch ``` Once confirmed, please delete the test branch: From c1d9ad410512346814e2a3474e3f6fc9494d42b8 Mon Sep 17 00:00:00 2001 From: sarahalsaady <148502402+salsaady@users.noreply.github.com> Date: Tue, 15 Jul 2025 23:40:18 -0400 Subject: [PATCH 3/3] add requested changes --- docs/ONBOARDING.md | 34 ++++++++++++++++++++++------------ 1 file changed, 22 insertions(+), 12 deletions(-) diff --git a/docs/ONBOARDING.md b/docs/ONBOARDING.md index 3659502..1527bf6 100644 --- a/docs/ONBOARDING.md +++ b/docs/ONBOARDING.md @@ -45,23 +45,33 @@ If not installed or the version is too old, install: - #### On macOS: - Download and install the latest version from: [https://www.python.org/downloads/](https://www.python.org/downloads/) + ```bash + brew install python + ``` ### 2. **Install `uv`** -Install the Python dependency manager `uv`: +Install the Python dependency manager `uv` using one of two ways: -```bash -curl -LsSf https://astral.sh/uv/install.sh | sh -``` +- Using pip/pipx: -Or using pip/pipx: + ```bash + pip install uv + # or + pipx install uv + ``` -```bash -pip install uv -# or -pipx install uv -``` +- Using the standalone installer: + + ```bash + curl -LsSf https://astral.sh/uv/install.sh | sh + ``` + + To update, run: + + ```bash + uv self update + ``` More details: [uv documentation](https://astral.sh/uv/) @@ -126,7 +136,7 @@ Test out running a specific file to make sure your setup is working: To run the full application: -`uv run python -m cumind` +`uv run python -m cumind --config configuration.json` ## 6. Test Your Git Setup