feat: Migrate to issue-based flow

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

@@ -1,64 +1,91 @@
-<!--
-  <<< 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:
+But don't worry! You don't need to know Docker or even have it installed on your machine!
 
-- 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.
+> [!TIP]
+> Since the Dev Container configuration is part of the repository, you can also use it locally with your own Docker host. Nice!
 
-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.
+A Codespace has several advantages/features compared to local development. To name a few:
 
-### :keyboard: Activity: Start a codespace
+- Start a codespace directly from the repository page.
+- Develop in the browser. No IDE installation required.
+  - Option to use a local install of VS Code to link to the remote Codespace.
+- Preconfigure everything you need to run the project:
+  - Add **[features](https://containers.dev/features)** to install common development needs.
+  - Run scripts at various steps of the codespace lifecycle _(e.g install python/npm packages)_.
+  - Setup VS Code settings and extensions to match the project needs.
+- Fast internet access (since the container is in the datacenter).
 
-**We recommend opening another browser tab to work through the following activities so you can keep these instructions open for reference.**
+> [!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 the incoming code changes.
 
-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.
+Let's get started! We'll start up a Codespace, run the application, make a change, and push it. Like normal development! 🤓
 
-   > Wait about 2 minutes for the codespace to spin itself up.
-   > **Note**: It's a virtual machine spinning up in the background.
+### ⌨️ Activity: Start a codespace
 
-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. Open a second tab and navigate to this repository. Ensure you are on the **Code** tab.
 
-### :keyboard: Activity: Push code to your repository from the codespace
+1. Above the files list on the right, click the green **<> Code** button.
 
-1. From inside the codespace in the VS Code explorer window, select the `index.html` file.
-1. Replace the **h1** header with the below:
+   <img width="300" alt="green code button" src="https://github.com/user-attachments/assets/a9d80b0d-4614-4b26-83dd-b4b6fefd76c9" />
 
-   ```html
-   <h1>Hello from the codespace!</h1>
+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.
+
+   > 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
    ```
 
-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
 
-   ```shell
-   git commit -a -m "Adding hello from the codespace!"
+1. Replace the `src/hello.py` file contents 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 commands.
 
-   ```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 didn't specify any configuration for the codespace we just created, so GitHub used a default Docker 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 lifecycle 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 configuration 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
+   touch .devcontainer/devcontainer.json
+   ```
+
+1. Open the `.devcontainer/devcontainer.json` file and add the following content.
 
-     "remoteUser": "codespace",
-     "overrideCommand": false
+   ```json
+   {
+     "name": "Python 3.10",
+     "image": "mcr.microsoft.com/vscode/devcontainers/python:3.10"
    }
    ```
 
-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.
+
+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.