diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..5791162 --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +devlog.md +CHANGES.md diff --git a/01-know-your-machine/README.md b/01-know-your-machine/README.md index dbf2134..8ad9089 100644 --- a/01-know-your-machine/README.md +++ b/01-know-your-machine/README.md @@ -10,9 +10,9 @@ Understand the basic hardware and software of the computer you are working on. - Understand what these components do and why they matter for computing tasks - Learn commands to query your system on macOS, Linux, and Windows -> **Read your *physical* machine first.** Sections 1–6 walk through inspecting the actual hardware you own. On macOS and Linux, the terminal reports directly from the hardware. On Windows, use **PowerShell** (or the Settings GUI) — those readings come straight from the real machine. +> **Read your *physical* machine first.** Sections 1–6 walk through inspecting the actual hardware you own. On macOS and Linux, the terminal reports directly from the hardware. On Windows, use **PowerShell** (or the Settings GUI). Those readings come straight from the real machine. > -> **Then visit the WSL VM separately (Section 7).** If you are on Windows and have WSL installed, your Linux environment is a *virtual machine* that sees only what it has been allocated. Section 7 covers how to inspect that and why it differs from the physical machine. If you do not yet have WSL installed, see [../WSL.md](../WSL.md). +> **Then visit the WSL VM separately (Section 7).** If you are on Windows and have WSL installed, your Linux environment is a *virtual machine* that sees only what it has been allocated. Section 7 covers how to inspect that and why it differs from the physical machine. If you do not yet have WSL installed, see [../WSL.md](../WSL.md) when you're ready. --- @@ -25,9 +25,9 @@ This module is a hands-on survey. Run the commands below on your own machine and Your operating system (OS) manages the hardware and provides the environment where all your programs run. The three major OS families are: -- **macOS** -- Apple's OS, based on Unix (Darwin kernel). Runs on Intel and Apple Silicon (M1/M2/M3/M4) hardware. Closely related to iOS, watchOS, and other Apple systems. (These are all, in fact, computers!) -- **Linux** -- Open-source Unix-like OS. Many distributions exist (Ubuntu, Fedora, etc.). Common on servers, clusters, and in WSL. -- **Windows** -- Microsoft's OS. For terminal-based work, we recommend the Windows Subsystem for Linux (WSL) to access a Unix environment. +- **macOS.** Apple's OS, based on Unix (Darwin kernel). It runs on Intel and Apple Silicon (M1/M2/M3/M4/M5) hardware. It's also closely related to iOS, watchOS, and other Apple systems. (These are all, in fact, computers!) +- **Linux.** An open-source Unix-like OS. Many distributions exist (Ubuntu, Fedora, etc.). Common on servers, clusters, and in WSL. +- **Windows.** Microsoft's OS. For terminal-based work, we recommend the Windows Subsystem for Linux (WSL) to access a Unix environment. ### Find your OS version @@ -61,11 +61,11 @@ This tells you the Windows version and architecture of the physical machine. ## 2. CPU (processor) -The CPU (Central Processing Unit) executes your code. Key properties: +The CPU (Central Processing Unit) executes your code. Key properties are: - **Architecture**: `x86_64` (Intel/AMD) or `arm64` (Apple Silicon, some Windows laptops). This affects which software binaries you can run. -- **Cores**: Modern CPUs have multiple cores that can work in parallel. More cores help with parallel tasks (compiling, running simulations, some ML training). -- **Clock speed**: Measured in GHz. Higher is faster for single-threaded tasks, but clock speed alone does not tell the whole story. +- **Cores**: Modern CPUs have multiple cores that can work in parallel. More cores help with parallel tasks (compiling, running simulations, and some ML training). +- **Clock speed**: Measured in GHz. Higher is faster for single-threaded tasks, but clock speed alone does not determine the system speed. ### Find your CPU @@ -95,7 +95,7 @@ Get-CimInstance Win32_Processor | Select-Object Name, NumberOfCores, NumberOfLog ### Why it matters -Heavy numerical work — simulations, data processing, training machine-learning models — runs faster with more cores and higher clock speed. Even so, CPUs are orders of magnitude slower than GPUs for highly parallel tasks like neural network training, which is why we also look at GPUs below. +Heavy numerical work (simulations, data processing, training machine-learning models) runs faster with more cores and higher clock speed. Even so, CPUs are orders of magnitude slower than GPUs for highly parallel tasks like neural network training, which is why we also look at GPUs below. > **Exercise 2:** What CPU does your machine have? How many cores? What architecture? @@ -129,7 +129,7 @@ This shows total, used, and available memory. The `-h` flag makes the output hum [math]::Round((Get-CimInstance Win32_ComputerSystem).TotalPhysicalMemory / 1GB, 1) ``` -This returns the **physical** RAM installed on the machine. WSL users: this is the number you want — running `free -h` inside WSL would only show the VM's allocation. See Section 7. +This returns the **physical** RAM installed on the machine. WSL users: this is the number you want. Running `free -h` inside WSL would only show the VM's allocation. See Section 7. **Windows (GUI):** Settings > System > About shows "Installed RAM". For current usage, open Task Manager (Ctrl+Shift+Esc) > Performance > Memory. @@ -137,15 +137,17 @@ This returns the **physical** RAM installed on the machine. WSL users: this is t Loading a large dataset or model weights means everything in active use has to fit in RAM. A modern large language model can be 4–8 GB or more; if you load one on an 8 GB machine alongside your OS, editor, and a browser, you may run out. When that happens the system swaps to disk and *everything* slows down dramatically. Knowing your RAM ceiling helps you plan what is realistic to run. -> **Exercise 3:** How much physical RAM does your machine have? Use the appropriate command for your OS above. How much is currently in use? +Everyday applications add up faster than you might expect. A browser with 30+ tabs can use 4–8 GB on its own (each tab is a sandboxed process); Slack, Teams, Zoom, Spotify, and a few Electron-based apps each take 500 MB to 1 GB. It is common to find that the OS and "nothing running" already consumes 6–10 GB before you have started any real work. Activity Monitor (macOS), Task Manager (Windows), or `htop` (Linux/WSL) will show you which process is using what. The point is awareness, not constant tidiness. Leaving apps open is fine for everyday work, but when a heavy job is about to run, knowing what is already in RAM tells you whether you have room or should close a window or appliation first. + +> **Exercise 3:** How much physical RAM does your machine have? Use the appropriate command for your OS above. How much is currently in use? What programs are using the most memory? ## 4. Storage (disk) Storage is where your files, programs, and OS live permanently. Unlike RAM, it persists when you shut down. The two main types: -- **SSD (Solid State Drive)**: Fast, no moving parts. Standard on modern laptops. -- **HDD (Hard Disk Drive)**: Slower, mechanical. Sometimes used for bulk storage. +- **SSD (Solid State Drive)**: Fast, no moving parts. Standard on modern laptops and boot volumes in many desktop computers. +- **HDD (Hard Disk Drive)**: Slower, mechanical. Often used as bulk or backup storage because they offer more capacity per dollar than SSDs. Common in external drives, network-attached storage (NAS), and as a secondary drive in desktops and workstations. ### Find your storage @@ -188,10 +190,10 @@ If you are low on storage, be selective about what you install, and clean up env ## 5. GPU (graphics processor) -A GPU (Graphics Processing Unit) was originally designed for rendering graphics, but its architecture (thousands of small cores optimized for parallel math) makes it excellent for machine learning. There are three common situations: +A GPU (Graphics Processing Unit) was originally designed for rendering graphics, but its architecture (thousands of small cores optimized for parallel math -- think matrix multiplication) makes it excellent for machine learning. There are three common situations: - **NVIDIA GPU (discrete)**: Found in gaming laptops and workstations. Supports CUDA, which PyTorch uses for fast training. This is the best case for ML work. -- **Apple Silicon GPU (integrated)**: The M1/M2/M3/M4 chips include a GPU that PyTorch can use via MPS (Metal Performance Shaders). Faster than CPU, slower than a dedicated NVIDIA GPU. +- **Apple Silicon GPU (integrated)**: The M1/M2/M3/M4/M5 chips include a GPU that PyTorch can use via MPS (Metal Performance Shaders). Faster than CPU, slower than a dedicated NVIDIA GPU. - **Intel/AMD integrated GPU**: Built into the CPU. Not usable by PyTorch. Use `--device=cpu`. ### Find your GPU @@ -217,7 +219,7 @@ If this command works, you have an NVIDIA GPU and the drivers are installed. It Get-CimInstance Win32_VideoController | Select-Object Name, AdapterRAM, DriverVersion ``` -This lists every GPU Windows sees on the physical machine — useful on laptops that have both an integrated GPU (Intel/AMD) and a discrete one (NVIDIA). +This lists every GPU Windows sees on the physical machine. Useful on laptops that have both an integrated GPU (Intel/AMD) and a discrete one (NVIDIA). **Windows (GUI):** Task Manager (Ctrl+Shift+Esc) > Performance > GPU. This shows the GPU name (e.g., "NVIDIA GeForce RTX 4060" or "Intel UHD Graphics"), memory, and utilization. @@ -233,7 +235,7 @@ This tells you what PyTorch can use on your machine. ### Why it matters -Training a small neural network on CPU takes minutes; on a GPU, seconds. The difference grows dramatically with model size — this is why large language models are trained on clusters of thousands of GPUs. For most introductory computing work, a CPU is sufficient. GPU acceleration is a bonus, not a requirement. +Training a small neural network on CPU takes minutes; on a GPU, seconds. The difference grows dramatically with model size. This is why large language models are trained on clusters of thousands of GPUs. For most introductory computing work, a CPU is sufficient. GPU acceleration is a bonus, not a requirement. > **Exercise 5:** What GPU (if any) does your machine have? Can PyTorch use it? Run the Python check above (if you have PyTorch installed). @@ -283,14 +285,14 @@ If you are on Windows and use the Windows Subsystem for Linux (WSL), your Linux ### Why this matters -When you install Python, run a model, or train something *inside WSL*, you are constrained by the VM's allocation, not the machine's full capacity. An 8 GB RAM cap inside WSL can mean a model loads fine on the Windows side but fails inside WSL. Knowing both numbers — physical and VM — lets you predict what will actually run where. +When you install Python, run a model, or train something *inside WSL*, you are constrained by the VM's allocation, not the machine's full capacity. An 8 GB RAM cap inside WSL can mean a model loads fine on the Windows side but fails inside WSL. Knowing both numbers (physical and VM) lets you predict what will actually run where. > **Exercise 7 (WSL users):** Run `free -h` and `df -h /` inside WSL. Compare the results to the PowerShell readings you recorded in Section 6. How much physical RAM does your VM actually see? How much of your physical disk is the VM using right now? ## 8. Keeping a machine log -Engineers keep logs for lab equipment, process equipment, and instruments. Your computer deserves the same treatment. Create a document called `machine_log` in your personal files and start it with the spec table from section 6. It should be a simple format — a text, rich text, or markdown file. +Engineers keep logs for lab equipment, process equipment, and instruments. Your computer deserves the same treatment. Create a document called `machine_log` in your personal files and start it with the spec table from section 6. It should be a simple format, such as a text, rich text, or markdown file. While you are at it, *give your machine a name* if you have not already. (On macOS: System Settings > General > About > Name. On Linux: `hostnamectl set-hostname yourname`. On Windows: Settings > System > About > Rename this PC.) A named machine is easier to reference in logs, SSH configs, and conversation, especially once you have more than one. Put the name at the top of your log. @@ -308,6 +310,6 @@ Keep entries short. Date, what changed, and the outcome. When something breaks m ## Additional resources -- [Crash Course Computer Science](https://www.youtube.com/playlist?list=PL8dPuuaLjXtNlUrzyH5r6jN9ulIgZBpdo) — episodes 1-10 cover hardware fundamentals (transistors, ALU, registers, RAM, CPU, instructions) at a reasonable pace -- J. Clark Scott, *But How Do It Know?* — a short, readable book that builds a computer from logic gates up. Good for understanding what is actually happening inside the machine. -- `top` and `htop` — interactive process viewers that show CPU, memory, and process usage in real time. `top` is the classic Unix tool and ships built-in on macOS and Linux, so it's always available. `htop` is a more modern third-party rewrite: colored CPU/memory bars, a scrollable process list, click-to-sort columns, F-keys (or mouse) to kill/renice/filter processes, an F5 tree view, and the same behavior everywhere (macOS `top` and Linux `top` differ in flags and output; `htop` does not). Install with `brew install htop` (macOS) or `sudo apt install htop` (Linux/WSL). Worth knowing both — `top` for "wherever I land," `htop` for daily use on your own machine. +- [Crash Course Computer Science](https://www.youtube.com/playlist?list=PL8dPuuaLjXtNlUrzyH5r6jN9ulIgZBpdo). Episodes 1–10 cover hardware fundamentals (transistors, ALU, registers, RAM, CPU, instructions) at a reasonable pace. +- J. Clark Scott, *But How Do It Know?*, a short, readable book that builds a computer from logic gates up. Good for understanding what is actually happening inside the machine. +- `top` and `htop`. Interactive process viewers that show CPU, memory, and process usage in real time. `top` is the classic Unix tool and ships built-in on macOS and Linux, so it's always available. `htop` is a more modern third-party rewrite: colored CPU/memory bars, a scrollable process list, click-to-sort columns, F-keys (or mouse) to kill/renice/filter processes, an F5 tree view, and the same behavior everywhere (macOS `top` and Linux `top` differ in flags and output; `htop` does not). Install with `brew install htop` (macOS) or `sudo apt install htop` (Linux/WSL). Worth knowing both. `top` for "wherever I land," `htop` for daily use on your own machine. diff --git a/02-git-basics/README.md b/02-git-basics/README.md index 715af79..7299fe1 100644 --- a/02-git-basics/README.md +++ b/02-git-basics/README.md @@ -15,7 +15,7 @@ Install git, configure your identity, and use it to download and stay current wi This module is **pull-focused**. Authentication, pushing your own commits, branching, and merging belong in a later module on git collaboration. For now, the goal is to *receive* updates reliably. -> **Windows users:** install WSL before starting this module — see [../WSL.md](../WSL.md). All commands below assume a Unix-style terminal (macOS, Linux, or WSL). +> **Windows users:** install WSL before starting this module. See [../WSL.md](../WSL.md). All commands below assume a Unix-style terminal (macOS, Linux, or WSL). --- @@ -23,7 +23,7 @@ This module is **pull-focused**. Authentication, pushing your own commits, branc Git is a **version control** system. It tracks changes to files over time, lets you go back to earlier states, and lets many people work on the same files without overwriting each other. -A **repository** (often "repo") is a folder that git is tracking. Public repositories on hosting services like [Gitea](https://about.gitea.com/), GitHub, or GitLab can be downloaded ("cloned") by anyone — no account needed. +A **repository** (often "repo") is a folder that git is tracking. Public repositories on hosting services like [Gitea](https://about.gitea.com/), GitHub, or GitLab can be downloaded ("cloned") by anyone. No account needed. For now we will use git only to *download* materials and *keep them up to date*. You will not need to push anything back, and you do not need an account on any hosting service. @@ -59,14 +59,14 @@ For other Linux distributions, use the appropriate package manager (`dnf install git --version ``` -You should see something like `git version 2.40.1`. If the command is not found, the install did not finish — try again. +You should see something like `git version 2.40.1`. If the command is not found, the install did not finish. Try again. > **Tip (WSL users):** Run all git commands from inside your Linux home directory (e.g., `~/repos`), not from `/mnt/c/...`. Mixing Windows-side and WSL-side git on the same folder leads to permission and line-ending headaches. ## 2. Configure your identity -Git stamps every commit with a name and email. Set yours once — these are labels on your local commits and do not need to match any account on a hosting service. +Git stamps every commit with a name and email. Set yours once. These are labels on your local commits and do not need to match any account on a hosting service. ```bash git config --global user.name "Your Name" @@ -104,7 +104,7 @@ This creates a folder named `cli-walkthrough` in your current directory. Move in cd cli-walkthrough ``` -> **Tip:** Be intentional about *where* you clone. Many people keep all their repos under one directory, e.g., `~/repos` or `~/code`. Avoid cloning into folders synced by Dropbox, iCloud, or OneDrive — sync conflicts and git history do not mix well. +> **Tip:** Be intentional about *where* you clone. Many people keep all their repos under one directory, e.g., `~/repos` or `~/code`. Avoid cloning into folders synced by Dropbox, iCloud, or OneDrive. Sync conflicts and git history do not mix well. ## 4. Check the state of a repository @@ -117,7 +117,7 @@ git status If you have not edited anything, you will see "nothing to commit, working tree clean." If you have edited files, git lists them. -`git status` is non-destructive. Run it whenever you are unsure what state things are in. It is the single most useful git command. +`git status` is non-destructive. Run it whenever you are unsure what state things are in. It is the most useful git command. ## 5. Pull updates @@ -132,9 +132,9 @@ Run this from inside the repo (the folder you `cd`'d into after cloning). **`git pull` does not silently overwrite your work.** -- If you have made no local changes → files update normally. -- If you have local changes that don't conflict with incoming changes → git merges them automatically. -- If there is a conflict → git **stops** and tells you exactly which files need attention. Your work is preserved. +- If you have made no local changes, files update normally. +- If your local changes don't conflict with the incoming ones, git merges them automatically. +- If there is a conflict, git stops and tells you exactly which files need attention. Your work is preserved. Get in the habit of running `git pull` before you start working in a shared repo, so you start from the latest version. @@ -157,7 +157,7 @@ This is also useful right before pulling updates — see section 7. Sometimes git declines to pull because you have uncommitted changes that overlap with incoming updates. Two safe ways out: -### Option A — Commit your work first +### Option A: Commit your work first ```bash git add . @@ -165,7 +165,7 @@ git commit -m "save before pull" git pull ``` -### Option B — Temporarily set work aside +### Option B: Temporarily set work aside ```bash git stash @@ -191,7 +191,7 @@ Do not run them unless you understand exactly what they do and have intentionall ## 9. If something looks wrong -First, do not panic. Git is conservative — it does not overwrite committed work without a clear instruction. Most "something is wrong" situations are recoverable. +First, do not panic. Git is conservative. It does not overwrite committed work without a clear instruction. Most "something is wrong" situations are recoverable. Run: @@ -210,7 +210,7 @@ Anonymous cloning and pulling work for **public** repositories. You will need au - Clone or pull from a **private** repository - Use collaboration features (branches, pull requests, etc.) -Those topics — personal access tokens, SSH keys, branching, merging, pushing — are the subject of a follow-on module on git collaboration. For now, pull is enough. +Those topics (personal access tokens, SSH keys, branching, merging, pushing) are the subject of a follow-on module on git collaboration. For now, pull is enough. ## Exercises diff --git a/03-editors/README.md b/03-editors/README.md index f15e1a8..5d28a59 100644 --- a/03-editors/README.md +++ b/03-editors/README.md @@ -9,7 +9,7 @@ A good editor is the cockpit you work from every day. It is worth a little setup - Install a modern code editor (VS Code recommended) and the essential extensions - Add an AI coding extension and understand the basic options - Configure a few editor settings that pay back the small investment quickly -- Know where to learn the *workflow* of using these tools — this module is setup, not practice +- Know where to learn the *workflow* of using these tools. This module is setup, not practice. --- @@ -21,8 +21,8 @@ A quick taxonomy: - **Code editors** (VS Code, Sublime Text, Neovim with plugins) understand programming languages: syntax highlighting, autocompletion, integrated terminal, version-control awareness, extensions for almost everything. - **IDEs** (PyCharm, IntelliJ IDEA, Visual Studio, Xcode) are heavier code editors tailored to a specific language or platform, with deeper refactoring tools and built-in build systems. Powerful but with more to learn. - **Terminal-based** (steep learning curves, devoted user bases): -Neovim — a modern Vim fork. The AI plugins like copilot.vim, avante.nvim, codecompanion.nvim are mature. -Emacs — also venerable, cross-platform, with AI packages like copilot.el and gptel. +**Neovim.** A modern Vim fork. The AI plugins like copilot.vim, avante.nvim, codecompanion.nvim are mature. +**Emacs.** Also venerable, cross-platform, with AI packages like copilot.el and gptel. For a general-purpose scientific computing setup, a code editor is the sweet spot. VS Code is the most widely used today and is what this module installs. @@ -33,10 +33,10 @@ For a general-purpose scientific computing setup, a code editor is the sweet spo A few alternatives worth knowing exist but aren't installed here: -- **Cursor** and **Windsurf** — forks of VS Code with deeper AI integration baked in (instead of bolted on as extensions). Same shortcuts, same UI, similar extension support. If you find yourself doing heavy agentic work, worth a look. -- **PyCharm** (Community Edition is free) — heavier IDE, strong refactoring tools, popular among Python-focused teams. -- **Neovim** with AI plugins — for the terminal-first crowd. Steep learning curve, satisfying for those who learn it. -- **Zed** — a newer, performance-focused editor with growing AI features. +- **Cursor** and **Windsurf**. Forks of VS Code with deeper AI integration baked in (instead of bolted on as extensions). Same shortcuts, same UI, similar extension support. If you find yourself doing heavy agentic work, worth a look. +- **PyCharm** (Community Edition is free). Heavier IDE, strong refactoring tools, popular among Python-focused teams. +- **Neovim** with AI plugins. For the terminal-first crowd. Steep learning curve, satisfying for those who learn it. +- **Zed**. A newer, performance-focused editor with growing AI features. Switching editors later is not a major event. Start with VS Code; revisit if you have a specific reason. @@ -78,10 +78,10 @@ After installing on any OS, open a terminal and run: code --version ``` -You should see version numbers. If the command is not found, VS Code is not on your PATH — fix it as follows: +You should see version numbers. If the command is not found, VS Code is not on your PATH. Fix it as follows: - **macOS:** open VS Code and run *Shell Command: Install 'code' command in PATH* from the command palette (`Cmd+Shift+P`). -- **Linux:** package-manager installs put `code` on the PATH automatically. A manually downloaded `.deb` or tarball may not — re-run the package installer or follow the instructions on the download page. +- **Linux:** package-manager installs put `code` on the PATH automatically. A manually downloaded `.deb` or tarball may not. Re-run the package installer or follow the instructions on the download page. - **Windows:** re-run the Windows installer and tick the "Add to PATH" option, or add the install directory manually. On Windows with WSL, the `code` command works from both PowerShell *and* your WSL shell (the WSL extension installs a shim inside WSL). @@ -142,10 +142,10 @@ After installation, you should see inline suggestions begin to appear as you typ Open Settings with `Cmd+,` (macOS) or `Ctrl+,` (elsewhere). A few that pay back the small investment: -- **Settings Sync** (the gear icon in the bottom-left → *Backup and Sync Settings*) — syncs your settings, extensions, and keybindings across machines using a GitHub or Microsoft account. Set up once; saves an afternoon every time you set up a new machine. +- **Settings Sync** (the gear icon in the bottom-left → *Backup and Sync Settings*). Syncs your settings, extensions, and keybindings across machines using a GitHub or Microsoft account. Set up once; saves an afternoon every time you set up a new machine. - **Integrated Terminal** (`` Ctrl+` `` / `` Cmd+` ``) — VS Code has a terminal built in. On Windows, you can set the default profile to WSL (open the terminal, click the dropdown next to the `+`, choose **Select Default Profile**, pick **Ubuntu** or your WSL distro). -- **Format on Save** — Settings → search for *Format On Save* → enable. Combined with a formatter extension (e.g., **Black** for Python, **Prettier** for JS/TS), this auto-formats every save. -- **Auto Save** — Settings → search for *Files: Auto Save* → set to `afterDelay` if you want VS Code to save automatically. Some people love it, some hate it; try it for a week. +- **Format on Save.** Settings → search for *Format On Save* → enable. Combined with a formatter extension (e.g., **Black** for Python, **Prettier** for JS/TS), this auto-formats every save. +- **Auto Save.** Settings → search for *Files: Auto Save* → set to `afterDelay` if you want VS Code to save automatically. Some people love it, some hate it; try it for a week. - **Themes** — `Cmd+Shift+P` → *Color Theme*. Cosmetic, but you stare at this thing for hours. Pick one you can read comfortably. @@ -164,9 +164,9 @@ Then create a small Python file, start typing a function signature, and see whet ## Where to go next -This module covered *setup*. Knowing **when** to copy-paste, **when** to use the editor, and **when** to use agents — and how to use each well — is the subject of a companion guide: +This module covered *setup*. Knowing **when** to copy-paste, **when** to use the editor, and **when** to use agents (and how to use each well) is the subject of a companion guide: -- [**coding-with-ai**](https://lem.che.udel.edu/git/furst/coding-with-ai) — Working effectively with AI coding assistants. The natural next step once your editor is configured. +- [**coding-with-ai**](https://lem.che.udel.edu/git/furst/coding-with-ai). Working effectively with AI coding assistants. The natural next step once your editor is configured. ## Exercises diff --git a/README.md b/README.md index 3a7ebfd..ef65cfa 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Computing Setup -A short, hands-on guide to getting your machine ready for scientific computing work. Inspect your hardware and operating system, install git, and learn enough to clone and pull from public repositories — the essentials before starting any computing course or project. +A short, hands-on guide to getting your machine ready for scientific computing work. Inspect your hardware and operating system, install git, and learn enough to clone and pull from public repositories, which are the essentials to learn before getting started on any computing course or project. ## Sections @@ -10,14 +10,14 @@ A short, hands-on guide to getting your machine ready for scientific computing w | [02](02-git-basics/) | **Git basics** | Install git, configure your identity, clone a public repository, and pull updates. Pull-focused — authentication and pushing come later. | | [03](03-editors/) | **Editors** | Install a modern code editor (VS Code recommended), add the essential extensions, and pick an AI coding extension. Configure a few settings that pay back the small investment quickly. | -This guide is designed for students starting a computing course, but should be useful for anyone setting up a new machine or getting acquainted with one they already own. A follow-on module on git collaboration (authentication, branching, merging, pushing) is planned. +This guide is designed for students starting a computing course, but should be useful for anyone setting up a new machine or getting acquainted with one they already own. ## Prerequisites -- A terminal — Terminal or iTerm on macOS, any terminal emulator on Linux, or PowerShell on Windows +- A terminal: Terminal or iTerm on macOS, any terminal emulator on Linux, or PowerShell on Windows - No prior command line or git experience required -**Windows users — no extra setup to start.** You can work through most of module 01 using PowerShell alone. You will want the Windows Subsystem for Linux (WSL) before tackling module 02 (git) and the optional WSL section at the end of module 01. See [WSL.md](WSL.md) when you get there. +**Windows users: no extra setup to start.** You can work through most of module 01 using PowerShell alone. You will want the Windows Subsystem for Linux (WSL) before tackling module 02 (git) and the optional WSL section at the end of module 01. See [WSL.md](WSL.md) when you get there. ## Getting started @@ -34,10 +34,10 @@ Each section has its own `README.md` with a walkthrough and exercises. Once you are comfortable with your machine, can pull updates with git, and have a working editor, two companion guides build on this one: -- [**cli-walkthrough**](https://lem.che.udel.edu/git/furst/cli-walkthrough) — a hands-on tour of the Unix command line: navigation, file manipulation, searching, processes, scripting, and remote access. -- [**coding-with-ai**](https://lem.che.udel.edu/git/furst/coding-with-ai) — working effectively with AI coding assistants. The *practice* counterpart to module 03's *setup*: when to copy-paste, when to use the editor, when to use an agent, and how to verify and cite what comes out. +- [**cli-walkthrough**](https://lem.che.udel.edu/git/furst/cli-walkthrough). A hands-on tour of the Unix command line, covering navigation, file manipulation, searching, processes, scripting, and remote access. +- [**coding-with-ai**](https://lem.che.udel.edu/git/furst/coding-with-ai). Working effectively with AI coding assistants. The *practice* counterpart to module 03's *setup*: when to copy-paste, when to use the editor, when to use an agent, and how to verify and cite what comes out. -Either order works. Many readers benefit from doing the cli-walkthrough first, since the command line shows up everywhere afterward. +Either order works. Many readers will benefit from doing the cli-walkthrough first, since the command line shows up everywhere afterward. ## License diff --git a/WSL.md b/WSL.md index 8400153..3794cab 100644 --- a/WSL.md +++ b/WSL.md @@ -12,7 +12,7 @@ Press `Win+R`, type `winver`, and press Enter. You need **Windows 10 build 19041 ### 2. Open PowerShell as Administrator -This is important — a normal PowerShell window will not work. +This is important. A normal PowerShell window will not work. - Click the **Start** button, type **PowerShell** - Right-click **Windows PowerShell** and select **Run as administrator** @@ -39,13 +39,13 @@ You should see progress output as it downloads and installs. ### 4. Restart your computer -When the install finishes, **restart your computer**. This is required — the features enabled in step 3 won't be active until you reboot. +When the install finishes, **restart your computer**. This is required. The features enabled in step 3 won't be active until you reboot. ### 5. Launch Ubuntu After restarting, open the **Start** menu and search for **Ubuntu**. Click it to launch. -The first time you open Ubuntu, it will spend a minute or two decompressing files. This is normal — just wait. +The first time you open Ubuntu, it will spend a minute or two decompressing files. This is normal. Wait it out. ### 6. Create your Linux username and password @@ -57,7 +57,7 @@ Enter new UNIX username: Pick a simple lowercase name with no spaces (e.g., `jsmith` or your UDel login). -Next, it will ask for a password. **Nothing will appear on screen while you type your password.** This is normal Linux behavior — it's not broken, it's just hiding your input for security. Type your password and press Enter. You'll be asked to confirm it. +Next, it will ask for a password. **Nothing will appear on screen while you type your password.** This is normal Linux behavior. It's not broken; it's hiding your input for security. Type your password and press Enter. You'll be asked to confirm it. ### 7. Verify it's working @@ -111,7 +111,7 @@ wsl --install --web-download -d Ubuntu Your computer's hardware virtualization may be disabled. You need to enable it in your BIOS/UEFI settings: -1. Restart your computer and enter the BIOS (usually by pressing `F2`, `F10`, `Del`, or `Esc` during boot — it varies by manufacturer) +1. Restart your computer and enter the BIOS (usually by pressing `F2`, `F10`, `Del`, or `Esc` during boot; this varies by manufacturer) 2. Look for a setting called **Intel VT-x**, **Intel Virtualization Technology**, or **AMD-V** (usually under CPU or Advanced settings) 3. Enable it, save, and restart