Skip to content

Commit 1645ffd

Browse files
simranjeevchawlasimranjeevchawla
authored
Initial commit
0 parents  commit 1645ffd

15 files changed

+1109
-0
lines changed

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

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
## Step 1: Start a codespace and push some code
2+
3+
### What's the big deal about Codespaces?
4+
5+
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!" 😎
6+
7+
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).
8+
9+
But don't worry! You don't need to know Docker or even have it installed on your machine!
10+
11+
> [!TIP]
12+
> Since the Dev Container configuration is part of the repository, you can also use it locally with your own Docker host. Nice!
13+
14+
A Codespace has several advantages/features compared to local development. To name a few:
15+
16+
- Start a codespace directly from the repository page.
17+
- Develop in the browser. No IDE installation required.
18+
- Option to use a local install of VS Code to link to the remote Codespace.
19+
- Preconfigure everything you need to run the project:
20+
- Add **[features](https://containers.dev/features)** to install common development needs.
21+
- Run scripts at various steps of the codespace lifecycle _(e.g install python/npm packages)_.
22+
- Setup VS Code settings and extensions to match the project needs.
23+
- Fast internet access (since the container is in the datacenter).
24+
25+
> [!TIP]
26+
> 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.
27+
28+
Let's get started! We'll start up a Codespace, run the application, make a change, and push it. Like normal development! 🤓
29+
30+
### ⌨️ Activity: Start a codespace
31+
32+
1. Open a second tab and navigate to this repository. Ensure you are on the **Code** tab.
33+
34+
1. Above the files list on the right, click the green **<> Code** button.
35+
36+
<img width="300" alt="green code button" src="https://github.com/user-attachments/assets/a9d80b0d-4614-4b26-83dd-b4b6fefd76c9" />
37+
38+
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.
39+
40+
1. Look in the bottom left of the VS Code window see the remote connection.
41+
42+
<img width="350" alt="remote connection status in VS Code" src="https://github.com/user-attachments/assets/35fa3230-db51-4a9d-a82b-3a1184e2e9a0"/>
43+
44+
> [!TIP]
45+
> 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.
46+
47+
### ⌨️ Activity: Run the application
48+
49+
1. Ensure you are in the VS Code Codespace.
50+
51+
1. In the left sidebar, select the file **Explorer** tab and open the file `src/hello.py`.
52+
53+
<img width="250" alt="vs code explorer tab" src="https://github.com/user-attachments/assets/76af1f05-1fed-43ff-b362-43d1c6c6cc53" />
54+
55+
1. In the lower panel, select the **TERMINAL** tab.
56+
57+
<img width="350" alt="vs code terminal tab" src="https://github.com/user-attachments/assets/9bb493b6-167c-4414-8f39-ab9c4baa5514" />
58+
59+
1. Paste the following command in the Codespace's remote terminal to show the installed versions of several tools. Note the versions for comparison later.
60+
61+
```bash
62+
node --version
63+
dotnet --version
64+
python --version
65+
gh --version
66+
```
67+
68+
1. Paste the following command to run the Python program in the Codespace's remote terminal.
69+
70+
```bash
71+
python src/hello.py
72+
```
73+
74+
### ⌨️ Activity: Push changes to your repository from the codespace
75+
76+
1. Replace the `src/hello.py` file contents with the following and save the file.
77+
78+
```py
79+
print("Hello World!")
80+
```
81+
82+
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.
83+
84+
```bash
85+
git add 'src/hello.py'
86+
git commit -m 'fix: incomplete hello message'
87+
git push
88+
```
89+
90+
1. (optional) Back in your web browser, open the `src/hello.py` file to to verify the change was updated.
91+
92+
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‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
## Step 2: Use a custom image in your codespace
2+
3+
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.
4+
5+
Let's do that now by providing a specific docker container image.
6+
7+
### How to configure a Codespace?
8+
9+
Configuration is provided directly in the repository via the `.devcontainer/devcontainer.json`. You can even add multiple configurations!
10+
11+
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.
12+
13+
### ⌨️ Activity: Customize the codespace
14+
15+
1. Ensure you are in the VS Code Codespace.
16+
17+
1. Use the VS Code file explorer to create the configuration file.
18+
19+
```txt
20+
.devcontainer/devcontainer.json
21+
```
22+
23+
Alternately, run the below terminal command to create it.
24+
25+
```bash
26+
mkdir -p .devcontainer
27+
touch .devcontainer/devcontainer.json
28+
```
29+
30+
1. Open the `.devcontainer/devcontainer.json` file and add the following content. Let's start with the default image.
31+
32+
```json
33+
{
34+
"name": "Universal - Latest",
35+
"image": "mcr.microsoft.com/devcontainers/universal:latest"
36+
}
37+
```
38+
39+
> 💡 **Tip**: The name is optional but it will help identify the configuration when creating a codespace on GitHub, if there are multiple options.
40+
41+
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.
42+
43+
<img width="350" alt="rebuild codespace command" src="https://github.com/user-attachments/assets/2b72e1a7-68c4-4c8d-8bf1-5727a520fd0e"/>
44+
45+
1. Wait a few minutes for the Codespace to rebuild and VS Code to reconnect.
46+
47+
1. Expand the lower panel and select the **TERMINAL** tab.
48+
49+
1. Paste the following command to view the versions of several tools. Notice they are the same from the previous step.
50+
51+
```bash
52+
node --version
53+
dotnet --version
54+
python --version
55+
gh --version
56+
```
57+
58+
1. With our new configuration verified, let's commit the changes. Use VS Code's source control tools or the below terminal command.
59+
60+
```bash
61+
git add '.devcontainer/devcontainer.json'
62+
git commit -m 'feat: Add codespace configuration'
63+
git push
64+
```
65+
66+
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.

‎.github/steps/3-customize-codespace.md‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
## Step 3: Add Features
2+
3+
You can further customize your codespace by adding container feature, VS Code extensions, VS Code settings, host requirements, and much more.
4+
5+
Let's add the GitHub CLI, extensions to run the python program using VS Code, and a custom script to install some packages when first creating the Codespace.
6+
7+
### ⌨️ Activity: Override the Python Version
8+
9+
1. In VS Code, open the Command Palette (`CTRL`+`SHIFT`+`P`) and select the below command.
10+
11+
```txt
12+
Codespaces: Add Dev Container Configuration Files...
13+
```
14+
15+
<img width="350" alt="vs code configure dev container command" src="https://github.com/user-attachments/assets/38265419-47bf-4ac8-a0fd-71ea67e2d6eb" />
16+
17+
1. Select the option `Modify your active configuration...`.
18+
19+
1. In the list of features, search for and select `Python`. Instead of the defaults, pick `Configure Options`. When it asks for he Python version, select `3.10`.
20+
21+
<!-- <img width="350" alt="select the github cli feature" src="https://github.com/user-attachments/assets/483b53ef-908d-4160-81e6-28fb977423a4" /> -->
22+
23+
1. Navigate to and open the `.devcontainer/devcontainer.json` file.
24+
25+
1. Verify a new entry similar to the below was added.
26+
27+
```json
28+
"features": {
29+
"ghcr.io/devcontainers/features/python:1": {
30+
"installTools": true,
31+
"version": "3.10"
32+
}
33+
},
34+
```
35+
36+
### ⌨️ Activity: Add VS Code extensions
37+
38+
1. In the left navigation, select the **Extension** tab.
39+
40+
<img width="200" alt="vs code extensions tab" src="https://github.com/user-attachments/assets/d7941711-e5a9-4871-83f3-c723c203bc70" />
41+
42+
1. Search for `python` and find entries for `Python` and `Python Debugger`.
43+
44+
<img width="250" alt="python extensions for vs code" src="https://github.com/user-attachments/assets/b34ef808-2023-41f2-8963-85ba04d5684b" />
45+
46+
1. Right click on each entry and select the `Add to devcontainer.json` option.
47+
48+
<img width="250" alt="add to devcontainer config button" src="https://github.com/user-attachments/assets/30ada390-c8a7-4175-9d83-dfa17fc83de3" />
49+
50+
1. Navigate to and open the `.devcontainer/devcontainer.json` file.
51+
52+
1. Verify a new entry similar to the below was added.
53+
54+
```json
55+
"customizations": {
56+
"vscode": {
57+
"extensions": [
58+
"ms-python.python",
59+
"ms-python.debugpy"
60+
]
61+
}
62+
},
63+
```
64+
65+
### ⌨️ Activity: Add a custom script
66+
67+
The Dev Container specification provides multiple locations to run [lifecycle scripts](https://containers.dev/implementors/json_reference/#lifecycle-scripts) to further customize your Codespace. Let's add the `postCreateCommand` which runs one time after initial build (or rebuild).
68+
69+
1. Use the VS Code file explorer to create a script file with the below name.
70+
71+
```txt
72+
.devcontainer/postCreate.sh
73+
```
74+
75+
Alternately, run the below terminal command to create it.
76+
77+
```bash
78+
touch .devcontainer/postCreate.sh
79+
```
80+
81+
1. Open the `.devcontainer/postCreate.sh` file and add the following code, which will install an animation of a steam locomotive.
82+
83+
```bash
84+
#!/bin/bash
85+
86+
sudo apt-get update
87+
sudo apt-get install sl
88+
echo "export PATH=\$PATH:/usr/games" >> ~/.bashrc
89+
echo "export PATH=\$PATH:/usr/games" >> ~/.zshrc
90+
```
91+
92+
1. Navigate to and open the `.devcontainer/devcontainer.json` file.
93+
94+
1. Create the `postCreateCommand` entry at the same level (_top level_) as `features`, and `customizations`.
95+
96+
```json
97+
"postCreateCommand": "bash .devcontainer/postCreate.sh"
98+
```
99+
100+
1. With our new configuration finished, let's commit the changes. Use VS Code's source control tools or the below terminal command.
101+
102+
```shell
103+
git add '.devcontainer/devcontainer.json'
104+
git add '.devcontainer/postCreate.sh'
105+
git commit -m 'feat: Add features, extensions, and postCreate script'
106+
git push
107+
```
108+
109+
1. Open the VS Code Command Palette (`CTRL`+`Shift`+`P`) and run the `Codespaces: Rebuild Container` command. Select the **Rebuild** option. A full build is not necessary.
110+
111+
<img width="350" alt="rebuild codespace command" src="https://github.com/user-attachments/assets/2b72e1a7-68c4-4c8d-8bf1-5727a520fd0e"/>
112+
113+
1. Wait a few minutes for the Codespace to rebuild and VS Code to reconnect.
114+
115+
1. With the customizations committed, Mona will begin checking your work. Give her a moment to provide feedback and the next learning steps.
116+
117+
> [!TIP]
118+
> You can also configure your account to [install dotfiles](https://docs.github.com/en/codespaces/setting-your-user-preferences/personalizing-github-codespaces-for-your-account), allowing you to combine personal configurations with the project's configuration.
119+
120+
### ⌨️ Activity: (optional) Verify our customizations
121+
122+
Now that you've rebuilt the codespace, let's verify the python extension, python version, and custom script were adjusted correctly in the Codespace.
123+
124+
1. Ensure you are in the Codespace.
125+
126+
1. In the left sidebar, click the extensions tab and verify that the Python extensions are installed and enabled.
127+
128+
<img width="250" alt="python extensions for vs code" src="https://github.com/user-attachments/assets/b34ef808-2023-41f2-8963-85ba04d5684b" />
129+
130+
1. In the left sidebar, select **Run and Debug** tab and then press the **Start Debugging** icon. VS Code will open the lower panel and show the run logs.
131+
132+
<img width="250" alt="run and debug tab pointing to start button" src="https://github.com/user-attachments/assets/63327b56-b033-4ca1-aa83-93ec076389f5"/>
133+
134+
1. In the lower panel, switch to the **TERMINAL** tab.
135+
136+
1. Run the following command to show the version of the installed GitHub CLI and Python
137+
138+
```bash
139+
node --version
140+
dotnet --version
141+
python --version
142+
gh --version
143+
```
144+
145+
> Notice the Python version is different but the others are the same. Adding the feature overwrote the version provided by the universal image.
146+
147+
1. Run the following command to show the steam locomotive animation.
148+
149+
```bash
150+
sl
151+
```

‎.github/steps/4-use-codespace.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
## Step 4: Test out our Codespace
2+
3+
The final test of our Codespace is to put ourselves in the position of an onboarding developer. Let's close everything and start up a new Codespace from nothing.
4+
5+
### ⌨️ Activity: Delete the existing codespace
6+
7+
1. Close the window running your VS Code Codespace.
8+
9+
1. Navigate to your exercise repository.
10+
11+
1. Above the files list on the right, click the green **<> Code** button.
12+
13+
1. Select the **Codespaces** tab to show the list of created Codespaces.
14+
15+
<img width="250" alt="list of codespaces" src="https://github.com/user-attachments/assets/2ed90b91-0c62-4c49-96f5-75abbb34a989" />
16+
17+
1. Find the active entry, select the three dot menu `...`, and select the **Delete** command.
18+
19+
<img width="500" alt="delete codespace command" src="https://github.com/user-attachments/assets/911a62a5-c50f-497b-a853-6e3865886211" />
20+
21+
> [!TIP]
22+
> You can manage all of your Codespaces across all projects at https://github.com/codespaces
23+
24+
### ⌨️ Activity: Start a codespace
25+
26+
1. Above the files list on the right, click the green **<> Code** button.
27+
28+
1. Select the **Codespaces** tab and click the **plus sign** `+` or **Create codespace on main** button.
29+
30+
> Alternately you can select the three dot menu `...` to choose a different machine type, location, or configuration.
31+
32+
1. Wait a few minutes for the Codespace to be created and VS Code to connect.
33+
34+
1. (optional) Test out some of the activities from the previous steps to see if they still work!
35+
36+
1. Add an issue comment to let Mona know you finished this activity, then give her a moment to share the final review.
37+
38+
```md
39+
Hey @professortocat, I've finished testing out my new Codespace.
40+
I'm ready to review!
41+
```
42+
43+
1. Nice work! You are all done! 🎉

‎.github/steps/x-review.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
## Review
2+
3+
<img src="https://octodex.github.com/images/welcometocat.png" alt=celebrate width=300 align=right>
4+
5+
Here's a recap of all the tasks you've accomplished in your repository:
6+
7+
- You learned how to create a codespace and push code to your repository from the codespace.
8+
- You learned how to use custom images, features, extensions, and scripts in your codespace.
9+
- You learned how to test run it like an onboarding developer.
10+
11+
### Additional learning and resources
12+
13+
- [Developing in a codespace](https://docs.github.com/en/codespaces/developing-in-codespaces/developing-in-a-codespace). Learn how to delete a codespace, open an existing codespace, connect to a private network, forward ports, and much more.
14+
- [Set up your repository](https://docs.github.com/en/codespaces/setting-up-your-project-for-codespaces/introduction-to-dev-containers). Learn how to set minimum machine specs for a codespace, add badges, set up a template repo, and much more.
15+
- [Personalize and customize GitHub Codespaces](https://docs.github.com/en/codespaces/customizing-your-codespace/personalizing-github-codespaces-for-your-account). Learn how to use setting sync for your codespace, add dotfiles, set the default region, set the default editor, and much more.
16+
- [Prebuild your codespace](https://docs.github.com/en/codespaces/prebuilding-your-codespaces/about-github-codespaces-prebuilds)
17+
- [Manage your codespace](https://docs.github.com/en/codespaces/managing-codespaces-for-your-organization/enabling-github-codespaces-for-your-organization)
18+
19+
### What's next?
20+
21+
- [Take another GitHub Skill exercise](https://github.com/skills).
22+
- [Read the Get started with GitHub docs](https://docs.github.com/en/get-started).
23+
- To find projects to contribute to, check out [GitHub Explore](https://github.com/explore).

0 commit comments

Comments
 (0)