feat: Migrate to issue-based flow

.github/steps/1-first-codespace.md

@@ -1,64 +1,99 @@
-<!--
-  <<< Author notes: Step 1 >>>
-  Choose 3-5 steps for your course.
-  The first step is always the hardest, so pick something easy!
-  Link to docs.github.com for further explanations.
-  Encourage users to open new tabs for steps!
--->
+## Step 1: Start a codespace and push some code
 
-## Step 1: Create your first codespace and push code
+### What's the big deal about Codespaces?
 
-_Welcome to "Develop code using GitHub Codespaces and Visual Studio Code"! :wave:_
+A **codespace** is a development environment hosted in the cloud, defined by configuration files in your repository. This creates a repeatable development environment tailored specifically to the project that simplifies developer onboarding and avoids the famous phrase "It works on my machine!" 😎
 
-**What's the big deal about using a codespace for software development?** A codespace is a development environment that's hosted in the cloud. You can customize your project for GitHub Codespaces by committing configuration files to your repository (also known as configuration-as-code), which creates a repeatable codespace configuration for all users of your project. Each codespace you create is hosted by GitHub in a Docker container that runs on a virtual machine. You can choose the type of machine you want to use depending on the resources you need.
+Each codespace follows the [Dev Container specification](https://containers.dev/implementors/spec/) and is hosted by GitHub as a [Docker container](https://code.visualstudio.com/docs/devcontainers/containers).
 
-GitHub offers a range of features to help your development team customize a codespace to reach peak configuration and performance needs. For example, you can:
+> [!TIP]
+> Since the Dev Container configuration is part of the repository, you can also use it locally with your own Docker host. Nice!
 
-- Create a codespace from your repository.
-- Push code from the codespace to your repository.
-- Use VS Code to develop code.
-- Customize the codespace with custom images.
-- Manage the codespace.
+A Codespace has several advantages/features compared to local development. To name a few:
 
-To begin developing using GitHub Codespaces, you can create a codespace from a template or from any branch or commit in a repository. When you create a codespace from a template, you can start from a blank template or choose a template suitable for the work you're doing.
+- Start a codespace directly from the repository page.
+- Use different hardware configurations.
+- Develop in the browser. No IDE installation required.
+- Use a local install of VS Code to link to the remote Codespace.
+- Add "feature layers" to the base image to install common development needs.
+- Apply VS Code settings specific to the project.
+- Run scripts at various steps of the codespace lifestyle.
+- Use custom images to customize anything Docker can customize.
+- Fast internet access (since the container is in the datacenter).
 
-### :keyboard: Activity: Start a codespace
+> [!TIP]
+> Codespaces are even useful in short-lived situations like reviewing a pull request. No need to verify you have the right setup to test out their code changes.
 
-**We recommend opening another browser tab to work through the following activities so you can keep these instructions open for reference.**
+Let's get started! We'll start up a Codespace, run the application, make a change, and push it. Like normal development! 🤓
 
-1. Start from the landing page of your repository.
-1. Click the green **Code** button located in the middle of the page.
-1. Select the **Codespaces** tab in the box that pops up and then click the **Create codespace on main** button.
+### ⌨️ Activity: Start a codespace
 
-   > Wait about 2 minutes for the codespace to spin itself up.
-   > **Note**: It's a virtual machine spinning up in the background.
+1. Open a second tab and navigate to this repository. Ensure you are on the **Code** tab.
 
-1. Verify your codespace is running. The browser should contain a VS Code web-based editor and a terminal should be present such as the below:
-   ![codespace1](https://user-images.githubusercontent.com/26442605/207355196-71aab43f-35a9-495b-bcfe-bf3773c2f1b3.png)
+1. Above the files list on the right, click the green **<> Code** button.
 
-### :keyboard: Activity: Push code to your repository from the codespace
+   <img width="300" alt="green code button" src="https://github.com/user-attachments/assets/a9d80b0d-4614-4b26-83dd-b4b6fefd76c9" />
 
-1. From inside the codespace in the VS Code explorer window, select the `index.html` file.
-1. Replace the **h1** header with the below:
+1. Select the **Codespaces** tab and click the **Create codespace on main** button. A new window will open running VS Code and it will connect to the remote Codespace.
 
-   ```html
-   <h1>Hello from the codespace!</h1>
+   > Wait a few minutes for the codespace to be created.
+
+1. Look in the bottom left of the VS Code window see the remote connection.
+
+   <img width="350" alt="remote connection status in VS Code" src="https://github.com/user-attachments/assets/35fa3230-db51-4a9d-a82b-3a1184e2e9a0"/>
+
+> [!TIP]
+> GitHub uses the [universal](https://github.com/devcontainers/images/tree/main/src/universal) Codespace image if the repository doesn't include a configuration. It includes several useful and commonly used tools.
+
+### ⌨️ Activity: Run the application
+
+1. Ensure you are in the VS Code Codespace.
+
+1. In the left sidebar, select the file **Explorer** tab and open the file `src/hello.py`.
+
+   <img width="250" alt="vs code explorer tab" src="https://github.com/user-attachments/assets/76af1f05-1fed-43ff-b362-43d1c6c6cc53" />
+
+1. In the lower panel, select the **TERMINAL** tab.
+
+   <img width="350" alt="vs code terminal tab" src="https://github.com/user-attachments/assets/9bb493b6-167c-4414-8f39-ab9c4baa5514" />
+
+
+1. Paste the following command in the Codespace's remote terminal to show the installed version of Python. Note the version for comparison later.
+
+   ```bash
+   python --version
+   ```
+
+1. Paste the following command to run the Python program in the Codespace's remote terminal.
+
+   ```bash
+   python src/hello.py
+   ```
+
+   Example response:
+
+   ```bash
+   Hello!
    ```
 
-1. Save the file.
-   > **Note**: The file should autosave.
-1. Use the VS Code terminal to commit the file change by entering the following commit message:
+### ⌨️ Activity: Push changes to your repository from the codespace
+
+1. If necessary, open the `src/hello.py` file.
 
-   ```shell
-   git commit -a -m "Adding hello from the codespace!"
+1. Replace the `Hello!` text with the following and save the file.
+
+   ```py
+   print("Hello World!")
    ```
 
-1. Push the changes back to your repository. From the VS Code terminal, enter:
+1. With the message updated, commit the change and push it to GitHub. Use VS Code's source control tools or the below terminal command.
 
-   ```shell
+   ```bash
+   git add 'src/hello.py'
+   git commit -m 'fix: incomplete hello message'
    git push
    ```
 
-1. Your code has been pushed to your repository!
-1. Switch back to the homepage of your repository and view the `index.html` to verify the new code was pushed to your repository.
-1. Wait about 20 seconds then refresh this page (the one you're following instructions from). [GitHub Actions](https://docs.github.com/en/actions) will automatically update to the next step.
+1. (optional) Back in your web browser, open the `src/hello.py` file to to verify the change was updated.
+
+1. With the the change pushed to GitHub, Mona will begin checking your work. Give her a moment to provide feedback and the next learning steps.

.github/steps/2-custom-image.md

@@ -1,54 +1,65 @@
-<!--
-  <<< Author notes: Step 2 >>>
-  Start this step by acknowledging the previous step.
-  Define terms and link to docs.github.com.
--->
+## Step 2: Use a custom image in your codespace
 
-## Step 2: Add a custom image to your codespace!
+The codespace we just created didn't specify any configuration, so GitHub used a default image. While this is very useful, it won't be consistent and it doesn't version lock our runtime environment. Specifying the configuration is important to keep the development environment repeatable.
 
-_Nice work! :tada: You created your first codespace and pushed code using VS Code!_
+Let's do that now by providing a specific docker container image.
 
-You can configure the development container for a repository so that any codespace created for that repository will give you a tailored development environment, complete with all the tools and runtimes you need to work on a specific project.
+### How to configure a Codespace?
 
-**What are development containers?** Development containers, or dev containers, are Docker containers that are specifically configured to provide a fully featured development environment. Whenever you work in a codespace, you are using a dev container on a virtual machine.
+Configuration is provided directly in the repository via the `.devcontainer/devcontainer.json`. You can even add multiple configurations!
 
-A dev container file is a JSON file that lets you customize the default image that runs your codespace, VS code settings, run custom code, forward ports and much more!
+Let's create this file and set a few of the most common settings. For other options like setting configuring VS Code, forwarding ports, and running lifetime scripts, see the [Codespaces documentation](https://docs.github.com/en/codespaces/setting-up-your-project-for-codespaces) on GitHub.
 
-Let's add a `devcontainer.json` file and add a custom image.
+### ⌨️ Activity: Customize the codespace
 
-### :keyboard: Activity: Add a .devcontainer.json file to customize your codespace
+1. Ensure you are in the VS Code Codespace.
 
-1. Navigating back to your **Code** tab of your repository, click the **Add file** drop-down button, and then click `Create new file`.
-1. Type or paste the following in the empty text field prompt to name your file.
+1. Use the VS Code file explorer to create the below file.
 
-   ```
+   ```txt
    .devcontainer/devcontainer.json
    ```
 
-1. In the body of the new **.devcontainer/devcontainer.json** file, add the following content:
+   Alternately, run the below terminal command to create it.
 
-   ```jsonc
-   {
-     // Name this configuration
-     "name": "Codespace for Skills!",
-     // Use the base codespace image
-     "image": "mcr.microsoft.com/vscode/devcontainers/universal:latest",
+   ```bash
+   mkdir -p .devcontainer
+   echo "" > .devcontainer/devcontainer.json
+   ```
+
+1. Open the `.devcontainer/devcontainer.json` file and add the following content.
 
-     "remoteUser": "codespace",
-     "overrideCommand": false
+   ```json
+   {
+     "name": "Python 3.12",
+     "image": "mcr.microsoft.com/vscode/devcontainers/python:3.12"
    }
    ```
 
-1. Click **Commit changes** and then select **Commit changes directly to the `main` branch**.
-1. Create a new codespace by navigating back to the **Code** tab of your repository.
-1. Click the green **Code** button located in the middle of the page.
-1. Click the **Codespaces** tab on the box that pops up.
-1. Click the **Create codespace on main** button OR click the `+` sign on the tab. This will create a new codespace on the main branch. (Notice your other codespace listed here.)
+   > 💡 **Tip**: The name is optional but it will help identify the configuration when creating a codespace on GitHub, if there are multiple options.
+
+1. After saving, VS Code likely popped up a notification that it detected a configuration change. You can **Accept** that option to rebuild the development container or manually use the Command Palette (`CTRL`+`Shift`+`P`) and run the command `Codespaces: Rebuild Container`. Select the **Rebuild** option. A full build is not necessary.
+
+   <img width="350" alt="rebuild codespace command" src="https://github.com/user-attachments/assets/2b72e1a7-68c4-4c8d-8bf1-5727a520fd0e"/>
 
-   > Wait about **2 minutes** for the codespace to spin itself up.
+1. Wait a few minutes for the Codespace to rebuild and VS Code to reconnect.
 
-1. Verify that your new codespace is running, as you did previously.
+1. Expand the lower panel and select the **TERMINAL** tab.
 
-   Note the image being used is the default image provided for GitHub Codespaces. It includes runtimes and tools for Python, Node.js, Docker, and more. See the full list here: https://aka.ms/ghcs-default-image. Your development team can use any custom image that has the necessary prerequisites installed. For more information, see [codespace image](https://aka.ms/configure-codespace).
+1. Paste the following command to view the installed version of Python.
+
+   ```bash
+   python --version
+   ```
+
+   > Notice it is different from the previous step, `3.12` instead of `3.13`.
+
+1. With our new configuration verified, let's commit the changes. Use VS Code's source control tools or the below terminal command.
+
+   ```bash
+   git add '.devcontainer/devcontainer.json'
+   git commit -m 'feat: Add codespace configuration'
+   git push
+   ```
 
-1. Wait about 20 seconds then refresh this page (the one you're following instructions from). [GitHub Actions](https://docs.github.com/en/actions) will automatically update to the next step.
+1. With our dev container configuration committed, Mona will begin checking your work. Give her a moment to provide feedback and the next learning steps.